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When you begin any enterprise, you must find a starting 
point. You set out from that starting point and acquire a basic 
vocabulary, a notion of boundaries and techniques, a sense 
of how things fit together and what is possible. For those 
who want to learn how to create OPENSTEP applications, 
this book provides a starting point. 

With this book you become familiar with OPENSTEP 
application development not merely by reading but by 
doing. The book guides you through the creation of three 
applications of increasing complexity. Along the way it 
explains related concepts and issues. The techniques and 
concepts you learn in one tutorial lay the foundation for the 
more advanced techniques and concepts in the next 
tutorial. 

The final chapter of the book tells you where to go for 
further information and where and how to find things, such 
as tools and documentation. It also tells you how to get 
NeXT products and services. 

This book covers a lot of ground, although sometimes at 
only a summary level. Finishing this book makes you much 
better prepared to take on serious application development 
with OPENSTEP in general and the Enterprise Object 
Framework in particular. 

Although the aim is primarily to educate, this book is also 
intended—for those interested in programming—to be fun. 


Some of you might be new to OPENSTEP. To learn more 
about OPENSTEP, the standard on which it’s based, and 
OPENSTEP Developer, turn the page. 
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Chapter 1 


Introduction to OPENSTEP 


What is OPENSTEP? 



OPENSTEP is NeXT Software's graphical, object-oriented user 
and development environment. It is based on the OpenStep 
standard and available on a variety of platforms. OPENSTEP is 
earning a growing reputation in the corporate world as the 
premier environment for developing and deploying mission- 
critical custom applications. 


OpenStep 

OpenStep is the software industry's first open standard for object- 
oriented software development It is an application programming 
interface (API) based on the fundamental NEXTSTEP object layer: 
the Application Kit, the Foundation Kit, and Display PostScript 


The two core components of the product are OPENSTEP User and 
OPENSTEP Developer. 

J OPENSTEP User is a user environment 

m acclaimed for its intuitively navigable desktop 

nbliicTiO anc ^ mana 9 er rt Y° u can eas| ty deploy 
OTOOity your own OPENSTEP applications as well as those 

supplied by NeXT and third-party vendors. Intelligent networking, 
particularly Netlnfo, makes it possible to install and upgrade 
OPENSTEP in a fraction of the time it takes other systems. 



OPENSTEP Developer, NeXT's software- 
development environment, provides 
seamlessly integrated set of tools for building 
complex applications that can be deployed on 
heterogeneous client/server networks running not only 
OPENSTEP, but Portable Distributed Objects, Enterprise Objects 
Framework, and OpenStep-based software developed by other 
vendors. 


The OpenStep object layer allows corporate customers to create, evolve 
and deploy multi-tier, client/server business applications in a fraction of 
time it takes other methods. 

• Application Kit: APIs for user-interface objects and for essential 
application behavior, such as event handling 

• Foundation Kit: APIs that define basic object behavior, that support 
object persistence and distribution, and that "objectify" collections, 
Unicode strings, and many other programmatic entities 



• Display PostScript: APIs for PostScript drawing 


What's in a Name? 

"OPENSTEP" refers to the software product "OpenStep" refers to the standard or specification on which the product is based, and by extension to the 
concepts expressed by the specification. 

The OpenStep specification is available via anonymous ftp at ftp. next. com. 
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The OPENSTEPuser 
environment includes File 
Viewer (a file-system browser), 
Mail, Preferences, Edit, and 
other applications in/NextApps. 



Other Products from NeXT 

• With WebObjects you can easily create dynamic websites. 
WebObjects applications provide a smart, interactive 
connection between corporate databases and customers on 
"The Web." 

• Enterprise Objects Framework enables you to construct 
applications that use (and reuse) enterprise business objects, 
storing them in relational databases such as those from Oracle 
and Sybase. 

• Portable Distributed Objects (PDO) allow objects in a single 


application to be distributed among a heterogeneous network 
of OpenStep clients and a broad range of servers. 

• D'OLE brings the PDO object model to the Windows platform, 
giving Windows application developers the ability to make use 
of distributed-object technology. 

In addition to software products, NeXT provides developer 
support and professional services, in particular the Object 
Experts program, an innovative on-site support and training 
program. 


OPENSTEP— Platforms and Interoperability 

Supported Platforms Intel-based PCs, Sun SPARC workstations, NeXT's Motorola 68040-based computers. 

NeXT has licensed SunSoft's implementation of the CORBA standard (from the Object Management 
Group) and is committed to CORBA interoperability. 


CORBA 
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Power Programming With OPENSTEP Dev 


. Jti .''. 


OPENSTEP Developer 4.0 is a programming environment ideally 
suited for the rapid development of custom object-oriented 
applications deployable on a variety of computer architectures. It 
comprises an integrated set of development software, libraries, 
header files, tools, documentation, and other resources. 


» Project Builder is an application that manages 
software-development projects, and that 
orchestrates and streamlines the development 
iaiiad process. It integrates a project browser, a full- 
featured code editor, language-sawy symbol recognition, 
sophisticated project search capabilities, header file and 
documentation access, build and debugging support, and a host 
of other features. 


rgr-Interface Builder makes it easy to create application 
' interfaces by dragging objects from palettes, 

j Standard palettes hold an assortment of Application 

Kit objects. Custom palettes can include third-party 
objects as well as the developer's own objects. Interface Builder 
archives and restores elements of a user interface as objects—it 
doesn't "hardwire" them into the interface. Interface Builder 
helps to connect objects for messaging, and it assists in the 
definition of custom classes. 



The main window of Project Builder 
combines a project browser with a 
code editor. 

Iconic buttons above the browser 
let you access the application's 
Build, Project Find, and Loaded Files 
panels , as well as the project 
inspector and the graphical 
debugger. 

When projects are indexed, Project 
Builder caches all symbols in 
memory and makes them instantly 
available upon request 


Controllers 


I_Tl. 21 .=.1.Sa.L.Saffii 

' | Classes j> |; r| Controll erm TT 

I Headers r Documents r* 

i|| Other Sources h )§§ DocumentView r* ■- 

Interfaces f- ■ ' simplePlayer. r . 
J Images r f§; § 

Other Resourc r- jjj j 

til Subprojects rs tUt . . 

El Supporting File t-:| U 

▼JlContext Help i- _|_ 


ttimport "Controller.h" 

#import "Document.h" 

ttimport "SimplePlayer_Globals.h' 


static NSString *curDirectory = nil; /* Directory for open panel */ 


^implementation Controller 


ill U Register our defaults 
WM + (void)initialize { 

$] if (self == [Controller class]) { 

NSDictionary *dict = [NSDictionary dictionaryWithObjectsAndKeys 
XI_ @"EvenMultiple3", O'^TUideoCellSizinq", _ 
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Interface Builder lets you craft user 
interfaces from palettes of ready’ 
made objects, then store the 
interface in a file. 

A palettes window contains 
assortments of standard 
Application Kit and (if installed) 
Enterprise Objects Framework 
objects as well as custom objects 
that you or third-party developers 
create. 

A nib file window enables the initial 
definition of custom classes and 
facilitates the connection of these 
classes to objects on the interface. 
It also catalogs the image and 
sound resources used in the 
interface. 


• OpenStep Class Libraries. Includes NeXT's implementation of 
the Application Kit, the Foundation Kit, and Display PostScript, 
with some extensions. 

• Objective-C. An object-oriented programming language that is 
an extension of standard ANSI C, Objective-C is a simple and 
powerful language. It is easy to learn, yet elegant in its 
application to the problem domain. OPENSTEP projects can 
include Objective-C, C, and C++ source code. 

In addition, OPENSTEP Developer 4.0 offers a new version of the 
GNU C compiler, enhancements to C++ compilation, and GNU 
make technology. 


Compiler and Library Technology. Two important features of 
OPENSTEP Developer 4.0 for Mach are dynamic shared 
libraries and frameworks. Programs linked with a dynamic 
shared library share one copy of that library's routines, and are 
linked with only those modules they currently need. 
Frameworks assemble all library components in one place: 
executable code, header files, resources, and documentation. 
The executable code is in the form of a dynamic shared library. 
The Application Kit, Foundation, and Display PostScript are 
installed as frameworks. 
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Objects are the software equivalent of the Industrial Revolution. 
In the same way that modern factories assemble products out of 
prefabricated components rather than manufacture every 
product from scratch, object-orientation allows programmers to 
build complex software by reusing software components called 
objects. Specifically, objects lead to several measurable 
advantages: 

Greater reliability. By breaking complex software projects into 
small, self-contained, and modular objects, object-orientation 
ensures that changes to one part of a software project will not 
adversely affect other portions of the software. Being small, each 
of these objects is a well-tested module of code, and so the 


overall reliability of the software increases. 



Greater maintainability. Since objects are modular and usually 
small (in terms of the overall code size of a project), bugs in code 
are easier to locate. Developers can also change the 


implementation of an object without causing havoc to other parts 
of an application. 

Greater productivity through reuse. One of the principal benefits 
of object-orientation is reuse. Objects can be integrated into 
many applications. And through subclassing you can create 
specialized objects merely by adding the code unique to the new 
object Objects of the new subclass inherit functionality from the 
superclass, reducing coding and promoting greater reliability. 


An Example 

Object-oriented programming delivers its greatest benefits to 
large and complex programs. But its advantages can also be 
demonstrated with a simple data structure such as might be used 
in any application. 

count dataPointer 


j 

ij |§I §11! $ fl > ; 




With procedural programming techniques, the application is 
directly responsible for data manipulation. One problem with this 
is illustrated in the picture above: It shows a data structure 
consisting of a count variable and a data pointer. Since the 
application directly manipulates the data, it has the opportunity to 
introduce inconsistencies. Here, it has added an item to the data, 
but has forgotten to increment the count; the count variable says 
there are still only two data elements when in fact there are three. 
The structure has become inconsistent and unreliable. 

Another problem is that all parts of the application must have 
intimate knowledge about the structure of the data. If the 
allocation of data elements were changed from a statically 
allocated array to a dynamically allocated linked list, it would 
affect every part of the application that accesses, adds, or 
deletes elements from the list 




With an object-oriented programming paradigm, the application 
as a whole wouldn't directly manipulate the data structure; 
rather, that task is entrusted to a particular object. Since the 
application doesn't directly access the data, it can't introduce 
inconsistencies. Note also that it's possible to change the 
implementation of the object without breaking other parts of the 
application. For example, the data storage method could be 
changedto optimize performance. So long asthe objectresponds 
to the same messages, other parts of the application are 
unaffected by internal implementation details. 











The Advantage of OPENSTEP 


Proven Technology. NeXT Software's technology has been 
evolving through 10 years and four major releases. During that 
time, it has been rigorously tested and iteratively refined. NeXT 
has an established track record in object technology, while it will 
be years before its major competitors can offer comparable 
technology of comparable maturity. 

True Objects. OPENSTEP objects are truly objects—modular, 
autonomous, persistent, and distributable. They are not static 
entities, but can be bound dynamically atrun time. When you drag an 
object from an Interface Builder palette, you're getting areal object 
and not an area painted on the screen with some code attached. 

Portability. OPENSTEP is designed to foster both hardware 
portability and operating-system portability. 

Simplified Client/Server Development. OPENSTEP Developer's 
integrated tooFset simplifies the complex process of building 
distributed client/server applications. 

Substantial Business Benefits. OPENSTEP's object-orientation 
helps managers to accelerate the introduction of new products 
and services that depend on new software. With OPENSTEP 
programmers can modify software quickly and assuredly to take 
advantage of evolving business opportunities. Through reusable 
object libraries, systems integrators can quickly customize a 
generic productto produce an individualized software solution for 
each client. 


Don't Take Our Word For It 

Here are a few comments on OPENSTEP and its predecessor, 

NEXTSTEP: 

• Booz Allen & Hamilton’s study of OPENSTEP development 
suggests that experienced developers could increase their 
productivity five to ten times. 

• "Information is our business. That's why OPENSTEP succeeds 
here. The most important product we have is the quality of the 
service we provide: our timeliness, the effectiveness of our 
analysis and planning." 

Director, Software Engineering 
Fannie Mae 

• "We would never have be able to do what we did on time or on 
budget if we had chosen any other solution but NeXT." 

Manager, IS Branch Automation 
Chrysler Financial Corporation 

• "The greatthing aboutobject-oriented programming isthatthe 
longer you're at the game, the more benefits you derive. You 
can reuse objects you've created or add to objects to make 
them more robust. And NEXTSTEP is the best integrated 
computer platform on the market." 

MIS Manager, 

UBS Securities 


In three years, Nicholas-Applegate 
Capital Management reengineered 
its business systems, enabling the 
company to manage its business 
growth from $4 billion to $14 billion 
in assets . Using object technology 
from NeXT, Nicholas-Applegate 
was able to develop an investment 
and trading environment that was 
flexible and able to expand as the 
company grew. 
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The application that you are going to create in this tutorial is called Currency 
Converter. It is a simple application, yet it exemplifies much of what software 
development with OpenStep is about. As you’ll discover, Currency Converter is 
amazingly easy to create, but it’s equally amazing how many features you get 
“for free”— as with all OpenStep applications. 

Currency Converter converts a dollar amount to an amount in another currency, 
given the rate of that currency relative to the dollar. Here’s what it looks like: 





Exchange Rate per$ 1 :|.45 -7— 

Dollars to Convert: (2000 § 

Am ount jn Other Currency: J 900 




' jt;' Convert : <•?) 



Enter an exchange rate and a dollar amount 


When you click the Convert button, the 
converted amount appears in the Amount in 
Other Currency field. 


Instead of clicking the button, you can also press the Return key. You can 
double-click the converted amount, copy it (with the Edit menu’s Copy 
command) and paste it in another application that takes text. You can tab 
between the first two fields. You can do many other things common to OpenStep 
applications. 


In this tutorial you’ll learn the basic things you must do to create a OpenStep 
application. You will discover how to: 


• Create a project. 

• Create an interface. 

• Create a custom subclass. 

• Connect an instance of the custom subclass to the interface. 

• Design an application using a common object-oriented design paradigm. 


You can find the 

CurrencyConverter project in the 
AppKit subdirectory of 

/NextDeveloper/Examples. 
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By following the steps of this chapter, you will become more familiar with the 
two most important OpenStep applications for program development: Interface 
Builder and Project Builder. You will also learn the typical work flow of 
OpenStep application development: 


fix errors or 
change 
design. 



Note: Although this chapter 
discusses the design of the 
application midway through the 
tutorial, application design can take 
place anytime in the early stages of 
a project, and in fact is often 
recommended as the first stage. 
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Creating the Currency Converter Project 


Every OpenStep application starts out as a project . A project is a repository for all 
the elements that go into the application, such as source code files, makefiles, 
frameworks, libraries, the application’s user interface, sounds, and images. You 
use the Project Builder application to create and manage projects. 


1 Launch Project Builder. 

In File Viewer navigate to the 
/NextDeveloper/Apps directory. 

Select ProjectBuilder.app and When Project Builder starts up, only its main menu appears on the screen. You 
double-click its icon (at right). . ~ ^ .. . , . . ™ XT 

must create or open a project to get Project Builder s mam window. 1 he New 

Project panel allows you to specify a new project’s name and location. 



2 Make a new project. 

Choose New from the Project 
menu (Project ►New). 

In the New Project panel, 
select the project location. 

Enter"CurrencyConverter" asthe 
project name. 

Click OK to create the project. 



New Project 


l- : . 


3 

2 

OEPresetPaths / 
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Procedures. / ..r 

Projects ' j 

SBoo’k'sbook ' 

SGS ENV > 
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r 

HleMgriest 1 “ 

Foreign Exchange r-j 

GopherBop r 

markgenref r~ 

NpwRunfilR .r* 

Z 

ii 

NewLegacy f' 

NewLibrary r- 

OrientExpress r 

0 

►L- - .IT Zj__£_1 


1 “-- — . 

CurrencyConverter 

ProjectType: Application *>*[ 


&l Ell £gl Cancel I 0K ^ 


Often projects are kept in a common 
directory. 


The name specified here becomes the 
name of the project directory and the 
default name of the application itself. 


Make sure Application is the project 
type. 


Project Builder creates a project directory named after the project—in this case 
CurrencyConverter—and populates this directory with an assortment of ready- 
made files and directories. It then displays its main window. 

Note: Here’s a variation on project creation: Create a project directory using File 
Viewer and then, in the New Project panel, navigate to that directory, type 
“PB.project” in the Name field, and click OK. 
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A makefile specifies file 
dependency relations and 
compiler and linker instructions 
for building the project. See 
OPENSTEP Development: Tips 
and Techniques for common 
changes to Makefile.preamble and 
Makefile.postamble. 



Currency Converter — -/Projects 


Done indexing project: Currency Converter 
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Command panel: Build, 
Find, Loaded Files, Project 
Inspector, Launcher/ 
Graphical Debugger. 


Project browser. Each 
"suitcase" is a project 
resource category. 


Code editor 


Go ahead and click an item in the left column of the project browser (a grouping 
of project resources sometimes called a “suitcase”); see what some of these 
suitcases contain already: 

• Other Sources: This suitcase contains CurrencyConverter.jTiain.ni, the main() routine 
that loads the initial set of resources and runs the application. (Do not modify 
this file!) 

• Interfaces: This suitcase contains CurrencyConverter.nib, the file that contains the 
application’s user interface. More on this file in the next step. 

• Supporting Files: This suitcase contains the project’s default makefiles and 
template source-code files. You can modify the preamble and postamble 
makefiles, but you must leave Makefile unchanged. 


Project Indexing 


ii 


When you create or open a project, after 
some seconds you may notice triangular 
"branch" buttons appearing after source 
code files in the browser. Project Builder has 
indexed these files. 

During indexing Project Builder stores all 
symbols of the project (classes, methods, 
globals, etc.) in virtual memory. This allows 
Project Builder to access project-wide 
information quickly. Indexing is 
indispensable to such features as name 
completion and Project Find. (More on these 
features later.) 


Usually indexing happens automatically 
when you create or open a project. You can 
turn off this option if you wish. Choose 
Preferences from the Info menu and then 
choose the Indexing display. Turn off the 
"Index when project is opened" switch. 

You can also index a project at any time by 
choosing Index Source Code from the 
Project menu. If you want to do without 
indexing (maybe you have memory 
constraints), choose Purge Indices from the 
Project menu. 
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Creating the Currency Converter Interface 

When you create an application project, Project Builder puts the main nib file in 
the Interfaces suitcase. A nib file is primarily a description of a user interface (or 
part of a user interface). The main nib file contains the main menu and any 
windows and panels you want to appear when your application starts up; at start¬ 
up time, each application loads the main nib file. 

At the beginning of a project, the main nib file is like a blank canvas, ready for 
you to craft the interface. Look in the Interfaces suitcase for nib files. 


1 Open the main nib file. 

Locate CurrencyConverter.nib in 
the project browser. 

Double-click to open. 


A nib file contains user-interface 
objects, definitions of custom 
classes, the connections between 
objects, and sounds and images 
that are used in the interface. 
Besides the main nib file, you can 
have nib files that you can load 
whenever you need them. These 
auxiliary nib files, and the 
techniques related to using them, 
are described in the “To Do 
Tutorial,” page 118 . See 
OPENSTEP Development: Tools 
and Techniques for an overview of 
nib files. 


To open, double-click the nib file name ...or double-click the icon Palette window 



By default, the window entitled “My Window” will appear when the application 
is launched. 

Note: The Interface Builder application is located in/NextDeveloper/Apps. The icon 
for the application is this: 
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A Window in OpenStep 



A window in OpenStep looks very similarto windows in other user 
environments such as Windows or Macintosh. It is a rectangular 
area on the screen in which an application displays controls, 
fields, text, and graphics. Windows can be moved around the 
screen and stacked on top of each other.like pieces of paper. A 
typical OpenStep window has a title bar, a content area, and 
several control objects. 


Miniaturize and close 
buttons 

resize bar 


Many user-interface objects other than the standard window 
depicted above are windows. Menus, pop-up lists, and pull-down 
lists are primarily windows, as are all varieties of panels: attention 
panels, inspectors, and tool palettes, to name a few. In fact, 
anything drawn on the screen must appear in a window. 

NSWindow and the Window Server 

Two interacting systems create and manage OpenStep windows. 
On the one hand, a window is created by the Window Server. The 
Window Server is a process integrating the NeXT Window 
System and Display Postscript. The Window Server draws, 
resizes, hides, and moves windows using Postscript primitives. 
The Window Server also detects user events (such as mouse 
clicks) and forwards them to applications. 

The window that the Window Server creates is paired with an 
object supplied by the Application Kit: an instance of the 
NSWindow class. Each physical window in an object-oriented 
program is managed by an instance of NSWindow (or subclass). 


its windows and tracks the current status of each. Each window, 
on the other hand, manages a hierarchy of views in addition to its 
PostScript window. 

At the "top" of this hierarchy is the content view, which fits just 
within the window's content rectangle. The content view 
encloses all other view (its subviews), which come below it in the 
hierarchy. The NSWindow distributes events to views in the 
hierarchy and regulates coordinate transformations among them. 


NSApp 
application object 



Another rectangle, the frame rectangle, defines the outer 
boundary of the window and includes the title bar and the 
window's controls. The lower-left corner of the frame rectangle 
defines the window's location relative to the screen's coordinate 
system and establishes the base coordinate system for the views 
of the window. Views draw themselves in coordinate systems 
transformed from (and relative to) this base coordinate system. 

See page 149 for more on the view hierarchy. 

Key and Main Windows 

Windows have numerous characteristics. They can be on-screen 
or off-screen. On-screen windows are "layered" on the screen in 
tiers managed by the Window Server. On-screen windows also 
can carry a status: key or main. 


When you create an NSWindow object, the Window Server 
creates the physical window that the NSWindow object will 
manage. The Window Server references the window by its 
window number, the NSWindow by its own identifier. 

Application, Window, View 

In a running OpenStep application, NSWindow objects occupy a 
middle position between an instance of NSApplication and the 
views of the application. (A view is an object that can draw itself 
and detect user events.) The NSApplication object keeps a list of 



Key windows respond to key presses for an application and are 
the primary recipient of action messages from menus and panels. 
Usually a window is made key when the user clicks it Key 
windows have black title bars. Each application can have only 
one key window. 

An application has one main window, which can often have key 
status as well. The main window is the principal focus of user 
actions for an application. Often user actions in a modal key 
window (typically a panel such as the Font panel or an inspector) 
have a direct effect on the main window. In this case, the title bar 
of the main window (when it is not key) is a dark gray. 
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2 Resize the window. 


3 Set the window's title and 
attributes. 

Click the window to select it. 

Choose Tools ► Inspector. 

Select the Attributes display from 
the pop-up list. 

Enter the window title. 

Turn off the resize option. 



Make the window smaller by 
dragging an edge of the window 
inward from a resize handle. 

Between the two resize handles 
is the resize bar, which permits 
only vertical resizing. 


Most objects on an interface have attributes that you can set in the Inspector 
panel’s Attributes display. 



J Attributes U\ 




i me:I (Currency Lonve 

r — Backing .. 

j C-Nonretained 

C Retained 
: O Buffered 

rtei — 

— ST Controls rrzzzr? 
Miniaturize yj 
Close^J 
Resize bar— 






Release when closed^] 

Hide on deactivate! J 

Visible at launch time|?| 
Deferred;^ 
OneshoFj 

Dynamic depth limirj 

Wants to be coloiTj 

■ 

. 

: i 


The title of the major window in 
an application is often the 
application name. 


When this option is turned off, 
the Windows's resize bar 
disappears. 
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4 Put a text field on the interface 
and resize and initialize it. 

Select the Views palette. 

Drag a text field from the palette 
onto the window. 


To initialize the text field, double¬ 
click "Text" and press Delete. 


Lengthen the text field. 


Put palette objects on the window using the “drag and drop” technique. 



Click this icon to select the Views 
palette. This palette contains an 
assortment of commonly used objects. 


Drag a text field and drop it (that is, 
release the mouse button) over the 
"surface" of the window. 


You must get rid of the word “Text” in this field; otherwise, that’s what the field 
will show when the nib file is loaded. 

The text field should be longer so it can hold more digits (you’re dealing with 
millions here): 


Currency Converter | V X 



Drag a resize handle in the direction 
you want the object to grow. 


Currency Converter needs two more text fields, both the same size as the first. 
You have two options: you can drag another object from the palette and make it 
the same size; or you can duplicate the first object 
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5 Duplicate an object. 

Select the text field. 
Choose Edit ► Copy. 
Choose Edit ► Paste. 


6 Make objects the same size. 

Drag a text field onto the window. 

Delete "Text" from the text field. 

Select the first text field. 

Shift-click to select the new text 
field. 

Choose Format ► Size ► Same 
Size 


7 Change the attributes of a text 
field. 

Select the third text field. 

Choose Tools** Colors. 

Select the grayscale palette of 
the Color panel. 

Select the gray color that is the 
same as the window background. 

Choose Tools ► Inspector. 

Select the Inspector panel's 
Attributes display. 

Drag the gray colorfrom the Color 
panel into the Background Color 
well. 

Turn off the Editable and 
Scrollable options. 



The new text field appears slightly offset 
from the original field. Reposition it under the 
first text field. 


Get the third field from the palette and make it the same size as the first field. 


| Currency Converter ' V 1*: 




i±E 

i ...„ 

3. a . 2 _ 

0 

...—1| 



2— 

: 



The first object you select should have the 
dimensions you want the other objects in the 
selection to take. 


Shift-click multiple objects to include them in 
the same selection. 


You’re not done yet with these text fields. The bottom text field displays the 
result of the computation. It should not be editable and therefore should, by 
convention, have a gray background. 



NSTextField Inspector 


Attributes 


Background Color 


Background jfj 


Text Color 


Border 


— Options — 
Editable jf 
ielectablajd 
Scrollable £| 


Brightness 


Click these 
buttons to get 
the grayscale 
palette. 


Drag the gray color into this well to set 
the background color. 


Click to get the color that blends the text 
field into the window background. 


With the Editable attribute turned off, 
users cannot alter the contents of the 
text field. 

Keep Selectable as an option so the user 
can select; copy, and paste the result to 
other applications. 


The Views palette provides a “Title” object that you can easily adapt to be a 
text-field label. (The title object is actually a text field, set to have a gray 
background and no border, and to be non-editable and non-selectable.) Text in 
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the title object is centered by default, but labels are usually aligned from the 
right. 


8 Assign labels to the fields. 

Drag a title object onto the 
window. 

Double-click to select the text 
"Title". 

Choose Format ►Text ► Align 
Right to align the text from the 
right. 



The text is highlighted when it is selected. 


The size of the text is rather large for a label, so change it. You set font family, 
typeface, and size with the standard OpenStep Font panel. 


Make sure the object's text is 
selected. 

Choose Format ► Font ► Font 
Panel. 

Set the label text to 16 points. 

Make two copies of the label. 

Position all labels to the left of 
their text fields. 
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— Use Family and Typeface- 

As selected above 


Be vert] 




Preview 


Set 


The font of this object is 18 point Helvetica. 
Click here and then click the Set button to set 
the font size to 16 points. 


When you cut and paste objects that contain text, like these labels, the object 
should be selected and not the text the object contains; if the text is selected, 
de-select it by clicking outside the text, then click the object again to select it. 


Type the text of each label. 


Currency Converter 


- 


II 


Exchange Rate per $ 1: [ 
[Doliars teTconvert: 


■■ ■ I 


WBB 


Title f~ 


■I I 

_ 




Bt 


Double-click to select title, then type the text 
of the label in place of the selection. 
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9 Add a button to the interface and 
initialize it. 

Drag the button object from the 
Views palette and put it on the 
lower-right corner of the window. 

Make the button the same size as 
a text field. 

Change the title of the button to 
"Convert". 


| Currency Converter [r [X 


You can resize buttons the same way you resize 
text fields or any other object on a window. 

Double-click the title of the button to select it 


Exchange Rate per$1: j * 

Dollars to Convert: 

Amount in Other Currency: | 

a Button 


You can easily give the button the capacity for responding to carriage returns in 
addition to mouse clicks. 


Select the Images display of the 
nib file window. 

Drag the NSReturnSign image to 
the main window and drop it over 
the button. 



\ SOWM1S : \ 


Convert 


NSHighlighied, 


NSHighiighted. 


NSReturnSign 


:N 88 witch 


Currency Converter 


Select a display of the nib file window 
by clicking a tab. 


Exchange Rate per $ 1: [ 
Dollars to Convert: [~ 
Amount in Other Currency: f 


After you drop the image 
over the button, the image 
appears (by default) to the 
right of the button title. 


If you check the attributes of the button in the Inspector panel, you’ll notice two 
things have been added: NSReturnSign is now listed as the button’s icon, and the 
Key field contains the escape sequence for a carriage return (\r). 

You’ve probably noticed that the final interface for Currency Converter (shown 
on the first page of this chapter) has a decorative line between the text fields and 
the button. This line is easy to make. 
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10 Create a horizontal decorative 
line. 

Drag a box object from the Views 
palette onto the interface. 

Bring up the Attributes display for 
the box (Command-!), select No 
Title, and setthe Vertical Offsetto 
zero. 

Drag the bottom-middle resize 
handle of the box upward until the 
horizontal lines meet. 

Position the line above the button. 

Drag the end points of the line 
until the line extends across the 
window. 



Exchange Rate per $ 1; f 
Dollars to Convert: [ 
Amount In Other Currency: [ 


Convert 


Currency Converter 


Drag upward until lines merge into one line. 


Fora black line (instead of white) click here. 


As you might have noticed, the Currency Converter has a main menu that holds, 
by default, the commands Info, Hide, and Quit, and the Edit, Services, and 
Windows menus. The menus contain ready-made sets of commands. The Edit 
menu includes commands for cutting, copying, and pasting text. The Windows 
menu lists the titles of open windows as well as common window commands. 
The Services menu allows your application to communicate with other 
applications, often with no work on the part of your application. For example, if 
your application handles text, you can use the Services menu to transfer 
information to other applications that accept text. 


Aligning on a Grid 


You can align objects on a window by 
imposing a grid on the window. When you 
move objects in this grid, they "snap" to the 


Alignment |f<| 


-Align --- 

Cleft edges/Bottomedges 
C Centers 

C Right edges /Top edges 



nearest grid intersection like nails to a 
magnet. You setthe edges of alignment and 
the spacing of the grid (in pixels) in the 
Alignment panel. Choose Format ►Align ► 
Alignment to displaythis panel. 

Be sure the grid is turned on before you move 
objects (Format ►Align ►Turn Grid On). 

You can move selected user-interface 
objects in Interface Builder by pressing an 
arrow key. When the grid isturned onthe unit 
of movement is whatever the grid is set to (in 
pixels). When the grid is turned off, the unit of 
movement is one pixel. 
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11 Align the text fields and labels in 
rows and columns. 

Select the three text fields and 
choose Format ► Align ► Make 
Column. 

Select the first text field and its 
label and choose Format ► 

Align ► Make Row. 

Repeat the last step for the 
second and third text fields and 
their labels. 


The nextKeyView variable is an 
outlet. An outlet is the identifier of 
an object that another object 
stores as an instance variable. 
Outlets enable communication 
between objects. See page 40 for 
more information on outlets. 


Creating the Currency Converter Interface 


Currency Converter’s interface is almost complete. One finishing touch might 
be to align the text fields and labels in neat rows and columns. Interface Builder 
gives you several ways to align selected objects on a window. 

• Dragging objects with the mouse 

• Pressing arrow keys (with the grid off, the selected objects move one pixel) 

• Using a reference object to put selected objects in rows and columns 

• Specifying origin points in the Size display of the Inspector panel 

• Using a grid (see preceding side bar) 

For Currency Converter, use the columns-and-rows technique. 




Exchange Rale per$1: J_ Q: . 

r-rsr-r-8 

Dollars to Convert: I 

0 

i— ■: 

- — a 

Amount in Other Currency: 

-a 

a 

Convert 



COLUMNS 

First select the objectwhose vertical position 
the other objects should adopt (the reference 
object). 


Shift-click the other objects to include them in 
the selection. 

Making a column evens the spacing between 
objects in the selection. 




: 

Exchange Rate per$1 

Dollars to Convert: 

a n 

^Amount in Other Currency: 

1 ... i 


1 !. 


J * 

His 

H Convert <HF ' 



ROWS 

When you make a row, the selected objects 
rest on a common horizontal baseline. 


The final step in composing the Currency Converter interface has more to do 
with behavior than appearance. You want the user to be able to tab from the first 
editable field to the second, and back again to the first. Many objects on 
Interface Builder’s palettes have an instance variable named nextKeyView. This 
variable identifies the next object to receive keyboard events when the user 
presses the Tab key (or the previous object if Shift-Tab is pressed). If you want 
inter-field tabbing you must connect fields through the nextKeyView variable. 
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12 Enable tabbing between text 
fields. 

Select the first text field. 

Control-drag a connection line 
from it to the second text field. 

In the Inspector panel 
(Connections display) select 
nextKeyView and click Connect. 

Repeat the same procedure, 
going from the second to the first 
field. 




■■■■. l . ini i 

Exchange Rate per$1: j f 


Dollars to Convert: || || 

Amount in Other Currency: | \_ 



* Convert' '<* 

* 


When you press Control and drag the mouse 
from an object, a connection line is drawn. 

When a line encloses the destination object 
release the mouse button. 


When you make a visual connection such as this, Interface Builder brings up the 
Connections display of the Inspector panel: 



Connections 


nextKevSubvie 


! nextKeyView 


J ' Disconnect^?! 


Revert 


NSText Field Inspector 


Outlets 


Connections 


[^[nextKeyView 

NSTextField j| 




The nextKeyView outltet identifies the next object to 
respond to events after the Tab key is pressed. 


Be sure to click the Connect button to confirm the 
connection (the button title then changes to Disconnect}. 


Don’t connect the nextKeyView outlet of the “Amount in Other Currency” field; 
this field is not supposed to be editable. 
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13 Test the interface. 

Choose Document ► Save to 
save the interface to the nib file. 

Choose Document ► Test 
Interface. 

Try various operations in the 
interface (see suggestions on the 
following page). 

When finished, choose Quit from 
the main menu. 


The CurrencyConverter interface is now complete. Interface Builder lets you 
test an interface without having to write one line of code. 

Note: You can also exit from test mode by double-clicking the Interface Buildfer 
icon, which changes to the following image to represent test mode: 
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An OpenStep Application — What You Get "For Free" 


The simplest OpenStep application, even one without a line of 
code added to it, includes a wealth of features that you get "for 
free": You do not have to program these features yourself. You can 
see this when you test an interface in Interface Builder. 

To enter test mode, choose Test Interface from the Document 
menu. Interface Builder simulates how your application (in this 
case, Currency Converter) would run, minus the behavior added 
by custom classes. Go ahead and try things out: move your 
windows, type in fields, click buttons. 

Application and Window Behavior 

In test mode Currency Converter behaves almost like any other 
application on the screen. Click elsewhere on the screen, and 
Currency Converter is deactivated, becoming totally or partially 
obscured by the windows of other applications. 



Reactivate Currency Converter by clicking on its window or by 
double-clicking its icon (the default terminal icon) in the 
workspace. Move the window around by its title bar. 

Here's some other tests you can make: 

• Click the Edit submenu in Currency Converter's main menu. It 
expands and contracts as in any application. 

• Click the miniaturize button or choose the Hide command. 
Double-click the document icon to get the window back. 

• Click the close box and the Currency Converter window 
disappears. (Choose Quitfromthe main menu and re-entertest 
mode to get the window back.) 

If we had configured Currency Converter's window in Interface 
Builder to retain the resize bar, we could also resize it now. We 
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could also have setthe auto-resizing attributes of the window and 
its views so thatthe window's objects would resize proportionally 
to the resized window or would retain their initial size (see 
OPENSTEP Programming: Tools and Techniquesior details on 
auto-resizing). 

Controls and Text 

The buttons and text fields of Currency Converter come with many 
built-in behaviors. Clickthe Convert button. Notice howthe button 
is highlighted momentarily. 



If you had buttons of a different style, such as radio buttons, they 
would also respond in characteristic ways to mouse clicks. 

Now click in one of the text fields. See howthe cursor blinks in 
place. Type some text and select it Use the commands in the Edit 
menu to copy it and paste it in the other text field. 

Do you recall the nextKeyView connections we made between 
Currency Converter's text fields? While a cursor is in a text field, 
press the Tab key and watch the cursor jump from field to field. 

When You Add Menu Commands 

An application you design in Interface Builder can acquire extra 
functionality with the simple addition of a menu command or 
submenu. You've already seen whatyou get with the Services and 
Windows menu, both included by default You can add other 
commands and submenus to the main menu for "free" 
functionality without compilation. For example: 

• The Font submenu adds behavior for applying fonts to text in 
NSText objects, such as the one in the scroll view object in the 
DataViews palette. Your application gets the Font panel and a 
font-manager object "for free." 

• The Text submenu allows you to align text anywhere there is 
editable text, and to display a ruler in the NSText object for 

tabbing, indentation, and alignment. 

■ . • 

Many objects that display text or images can print their contents 
as PostScript data. Later you'll learn how to add the Print menu 
command and have it invoke this capability. 
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An OpenStep Application — The Possibilities 

L_______________ 


An OpenStep application can do an impressive range of things 
without a formidable programming effort on your part. 

Document Management 

Many applications create and manage semi-autonomous objects 
called documents ■ Documents contain discrete sets of 
information and support the entry and maintenance of that 
information. A word-processing document is a typical example. 
The application coordinates with the user and communicates 
with its documents to create, open, save, close and otherwise 
manage them. 

The final tutorial in this book describes how to create an 
application based on a multi-document architecture. 

File and Account Management 

An application can use the Open panel of the Application Kit to 
help the user locate files in the file system and open them. It can 
also make the Save panel available for saving information in files. 
NeXT's version of OpenStep also provides classes for managing 
files in the file system (creating, comparing, copying, moving, and 
so forth) and for managing system-account information and user 
defaults. 

Communicating With Other Applications 

OpenStep gives an application several ways of communicating 
information to and from other applications: 

• Pasteboard: The pasteboard is a global facility for sharing 
information among applications. Applications can use the 
pasteboard to hold data that the user has cut or copied and 
may paste into another application. 

• Services: Any application can avail itself of the services 
provided by another application, based on the type of the 
selected data (such as text). An application can also provide 
services to other applications such as encryption, language 
translation, or record-fetching. 

• Drag-and-drop: If your application implements the proper 
protocol, users can drag objects to and from the interfaces of 
other applications. 

Editing Support 

You can get several panels (and associated functionality) when 
you add a submenu to your application's main menu in Interface 
Builder. These "add-ons" includes the Font panel (and font 


management), the Color panel (and color management), and, 
although it's not a panel, the text ruler and the tabbing and 
indentation capabilities it provides. 

Formatter classes enable your application to format numbers, 
dates, and other types of field values. Support for validating the 
contents of fields is also available. 


With just a simple Interface Builder procedure, OpenStep 
automates simple printing and faxing of views that contain text or 
graphics. When a user clicks the control, an appropriate panel 
helps to configure the print or fax process. The output is 
WYSIWYG. 

Several Application Kit classes give you greater control over the 
printing of documents and forms, including features such as 
pagination and page orientation. 


You can create a help system for your application using Interface 
Builder, Project Builder, and an RTF text editor (such as Edit). The 
Application Kit includes an class for context-sensitive help. If the 
user clicks an object on the application's interface while pressing 
a Help key, a small window is displayed containing concise 
information on the object. 

Custom Drawing and Animation 

OpenStep lets you create your own custom views that draw their 
own content and respond to user actions. To assist you in this, 
OpenStep provides image-compositing and event-handling API 
as well as PostScript operators, operator functions, and client 
library functions. 


You can design some applications so that users can incorporate 
new modules later on. For example, a drawing program could 
have a tools palette: pencil, brush, eraser, and so on. You could 
create a new tool and have users install it. When the application 
is next started, this tool appears in the palette. 


Plug and Play 


Printing and Faxing 


Help 
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Designing the Currency Converter Application 

An object-oriented application should be based on a design that identifies the 
objects of the application and clearly defines their roles and responsibilities. You 
normally work on a design before you write a line of code. You don’t need any 
fancy tools for designing many applications; a pencil and a pad of paper will do. 

Currency Converter is an extremely simple application, but there’s still a design 
behind it. This design is based upon the Model-View-Controller paradigm, a 
model behind many designs for object-oriented programs (see “The Model- 
View-Controller Paradigm” on page 36). This design paradigm aids in the 
development of maintainable, extensible, and understandable systems. But 
first, you might want to read the sidebar below to understand the symbol used 
in the design diagram. 

Note: This design for Currency Converter is intended to illustrate a few points, 
and so is perhaps overly designed for something so simple. It is quite possible to 
have the application’s controller class, ConverterController, do the computation 
and do without the Converter class. 


Why an Object is Like a Jelly Donut 

This book depicts objects as filled and segmented "donuts." Why 
this unlikely shape? 



This symbol illustrates data encapsulation, the essential 
characteristic of objects. An object consists of both data and 
procedures for manipulating thatdata. Other objects or external 
code cannot access that data directly, but must send messages 
to the object requesting its data. 

An object's procedures (called methods) respond to the message 


and may return data to the requesting object. As the symbol 
suggests, an object's methods do the encapsulating, in effect 
mediating access to the object's data. An object's methods are 
also its interface, articulating the ways in which the object 
communicates with the world outside it. 

The donut symbol also helps to convey the modularity of objects. 
Because an object encapsulates a defined set of data and logic, 
you can easily assign it to particular duties within a program. 
Conceptually, it is like a functional unit—for instance, "Customer 
Record"—that you can move around on a design board; you can 
then plot communication paths to and from other objects based 
on their interfaces. 

See the appendix "Object Oriented Programming," for a fuller 
description of data encapsulation, messages, methods, and other 
properties of objects. 
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Designing the Currency Converter Application 


You can divide responsibility within Currency Converter among two custom 
objects and the user interface, taken as a collection of ready-made Application 
Kit objects. The Converter object is responsible for computing a currency 
amount and returning that value. Between the user interface and the Converter 
object is a controller object, ConverterController. ConverterController coordinates 
the activity between the Converter object and the UI objects. 



ConverterController 


The ConverterController class assumes a central role. Like all controller objects, 
it communicates with the interface and with model objects, and it handles tasks 
specific to the application, such as managing the cursor. ConverterController 
gets the values users enter into fields, passes these values to the Converter 
object, gets the result back from Converter, and puts this result in a field in the 
interface. 

The Converter class merely computes a value from two arguments passed into 
it and returns the result. As with any model object, it could also hold data as well 
as provide computational services. Thus, objects that represent customer 
records (for example) are akin to Converter. By insulating the Converter class 
from application-specific details, the design for Currency Converter makes it 
more reusable, as you’ll see in the Travel Advisor tutorial. 
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A common and useful paradigm for object-oriented applications, 
particularly business applications, is Model-View-Controller 


(MVC). Derived from Smalltalk-80, MVC proposes three types of 
objects in an application, separated by abstract boundaries and 
communicating with each other across those boundaries. 



Model Objects 

This type of object represents special knowledge and expertise. 
Model objects hold a company's data and define the logic 
that manipulates that data. For example, a Customer object, 
common in business applications, is a Model object. It holds data 
describing the salient facts of a customer and has access to 
algorithms that access and calculate new data from those facts. 
A more specialized Model class might be one in a meteorological 
system called Front; objects of this class would contain the data 
and intelligence to represent weather fronts. Model objects are 
not displayable. They often are reusable, distributed, persistent 
and portable to a variety of platforms. 

View Objects 

A View object in the paradigam represents something visible on 
the user interface (a window, for example, or a button). A View 
object is "ignorant" of the data it displays. The Application Kit 
usually provides all the View objects you need: windows, text 
fields, scroll views, buttons, browsers, and so on. But you might 
want to create your own View objects to show or represent your 
data in a novel way (for example, a graph view). You can also 
group View objects within a window in novel ways specific to an 
application. View objects, especially those in kits, tend to be very 
reusable and so provide consistency between applications. 


Controller Object 

Acting as a mediator between Model objects and View objects in 
an application is a Controller object. There is usually one per 
application or window. A Controller object communicates data 
back and forth between the Model objects and the View objects. 
It also performs all the application-specific chores, such as 
loading nib files and acting as window and application delegate. 
Since what a Controller does is very specific to an application, it 
is generally not reusable even though it often comprises much of 
an application's code. (This last statement does not mean, 
however, that Controller objects cannot be reused; with a good 
design, they can.) 

Because of the Controller's central, mediating role, Mode! 
objects need not know about the state and events of the user 
interface, and View objects need not know about the 
programmatic interfaces of the Model objects. You can make your 
View and Model objects available to others from a palette in 
Interface Builder. 

Hybrid Models 

MVC, strictly observed, is not advisable in all circumstances. 
Sometimes its best to combine roles. For instance, in a graphics¬ 
intensive application, such as an arcade game, you might have 
several View objects that merge the roles of View and Model. 

In some applications, especially simple ones, you can combine 
the roles of Controller and Model; these objects join the special 
data structures and logic of Model objects with the Controller's 
hooks to the interface. 

A Note on Terminology 

The Application Kit and Enterprise Objects Framework reserve 
special meanings for "vew object" and "model." A view object in 
the Application Kit denotes a user-interface object that inherits 
from NSView. In the Enterprise Objects Framework, a model 
establishes and maintains a correspondence between an 
enterprise object class and data stored in a relational database. 
This book uses "model object" only within the context of the 
Model-View-Controller paradigm. 
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Defining the Classes of Currency Converter 

Interface Builder is a versatile tool for application developers. It enables you not 
only to compose the application’s graphical user interface, but it gives you a way 
to define much of the programmatic interface of the application’s classes and to 
connect the objects eventually created from those classes. 

You must go to the Classes display of the nib file window to define a class. Once 
there, the first thing you must do is select the superclass , the class your new 
subclass will inherit from. Let’s start with the ConverterController class. 


1 Specify a subclass. 

Goto the Classes display of the 
nib file window. 

Select NSObject, the superclass 
of your custom classes. 

Choose Subclass from the pull¬ 
down Operations menu. 


. Currency Con verter.nib ...rter/English.lproj'i 




a 


o NSObjectv 
O FirstResp'bnder 
o iBInspectar* 

.QlBPalette .. 

43 My NS Object 
6 NS Array 
0 NSCetl 
O NS Curs or 
O NS Diction ary 
o NSFontMarraaer 


0 © 

0 47 © 

10 4 © 

10 0 


-a- 

—©— 

0 

' !• 

0 

4 © ! 

0 

© i;:: 

0 

© is 

1 0 

3 © 


| Operations 


Click to select the Classes display. 


NSObject, the root class, is the class that 
ConverterController will inherit from. 


The Subclass command in this pull-down 
menu generates a new subclass. 


After you choose the Subclass command, “MyNSObject” appears under 
“NSObject” highlighted. 


Class Versus Object 

To newcomers to the subject, explanations of object-oriented 
programming might seem to use the terms "object" and "class" 
interchangeably. Are an object and a class the same thing? And if 
not, how are they different? How are they related? 

An object and a class are both programmatic units. They are 
closely related, but serve quite different purposes in a program. 

First, classes provide a taxonomy of objects, a useful way of 
categorizing them. Just as you can say a particular tree is a pine 
tree, you can identify a particular object by its class. You can 
thereby know its purpose and what messages you can send it. In 
other words, a class describes the type of an object. 

Second, you use classes to generate instances —or objects. 
Classes define the data structures and behavior of their 
instances, and at run time create and initialize these instances. 
In a sense, a class is like a factory, stamping out instances of itself 
when requested. 


What especially differentiates a class from its instance is data. A 
instance has its own unique set of data but its class, strictly 
speaking, does not. The class defines the structure of the data its 
instances will have, but only instances can hold data. 

A class, on the other hand, implements the behavior of all of its 
instances in a running program. The donut symbol used to 
represent objects is a bit misleading here, because it suggests 
that each object contains its own copy of code. This is fortunately 
not the case; instead of being duplicated, this code is shared 
among all current instances in the program. 

Implicit in the notion of a taxonomy is inheritance, a key property 
of classes. Classes exist in a hierarchical relationship to one 
another, with a subclass inheriting behavior and data structures 
from its superclass, which in turn inherits from its superclass. 

See the appendix, "Object-Oriented Programming," for more on 
these and other aspects of classes. 
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Enterthe name of the subclass: 
"ConverterController." 

Press Return. 


See Paths for Object 
Communication: Outlets , Targets , 
and Actions on page 40. for a more 
detailed description of outlets 
and actions. See page 103 for 
more on control objects and their 
relation to cells and formatters. 
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After you name the class, it appears 
indented under its superclass in 
alphabetical order. 


To see subclasses of a class, click a filled 
button (if the button is unfilledthere are no 
subclasses). 

NSCell, for example, has several levels of 
subclasses; each level is indicated by 
indentation. 


Now your class is established in the hierarchy of classes within the nib file. Next, 
specify the paths for messages travelling between the ConverterController 
object and other objects. In Interface Builder you specify these paths as outlets 
and actions . 


Before You Go On - 

Here’s some basic terminology: 

Outlet An object held as an instance variable and typed as id. Objects in 
applications often hold outlets as part of their data so they can send messages to 
the objects referenced by the outlets. An outlet lets you keep track of or 
manipulate something in the interface. 

id The generic (or dynamic) type of objects (technically the address of an 
object). 

Action Refers both to a message sent to an object when the user clicks a button 
or manipulates some other control object and to the method that is invoked. 

Control object A user-interface object (a device) with which users can interact to 
affect events in the application. Control objects include buttons, text fields, 
forms, sliders, and browsers. All control objects inherit from NSControl. 
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2 Define your class's outlets. 

In the nib file window, click the 
electrical-outlet icon to the right 
of the class. 

Choose Add Outlet from the 
Operations pull-down menu 

Type the name of the outlet over 
the highlighted "myOutlet." Name 
the first outlet rateField. 

Press Return. 

Repeat the last three steps to 
define two other outlets: 

dolIarField 

totalField 


3 Define your class's actions. 

In the Classes display of the nib 
file window, click the crosshairs 
icon. 

Choose the Add Action command 
from the Operations pull-down 
menu. 

Type the name of the action 
method, convert:. 

Press Return. 
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Click here to begin specifying outlets. 


"Outlets" appears indented underneath, 
highlighted (not shown}. 

Instead of choosing Add Outlets from the 
Operations menu, you can press Return 
when "Outlets" is highlighted to add an 
outlet 
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ConverterController has one action method, convert:. When the user clicks the 
Convert button, a convert: message is sent to the target object, an instance of 
ConverterController. 
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The crosshairs suggest the "target" in the 
targel/action paradigm. 

After you chose Add Action "myAction" 
appears indented under "Actions." 

You only need to type convert here- 
Interface Builder adds the colon. 


Before You Go On -- 

Add an outlet: ConverterController needs to access the text fields of the interface, 
so you’ve just provided outlets for that purpose. But ConverterController must 
also communicate with the Converter class (yet to be defined). To enable this 
communication, add an outlet named converter to ConverterController. 
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Outlets When You Make a Connection in Interface Builder 


As with any instance variable, outlets must be initialized at run 
timeto some reasonable value—in this case, an object's identifier 
(id value). Because of Interface Builder, an application can 
initialize outlets when it loads a nib file. 

When you make a connection in Interface Builder, a special 
connector object holds information on the source and destination 
objects of the connection. (The source object is the object with 
the outlet.) This connector object is then stored in the nib file. 
When a nib file is loaded, the application uses the connector 
object to set the source object's outlet to the identifier of the 
destination object. 

It might helpto understand connections by imagining an electrical 
outlet (as used in the Classes display of the nib file window) 
embedded in the destination object. Also picture an electrical 
cord extending from the outlet in the source object Before the 
connection is made the cord is unplugged and the value of 
destination is undefined; afterthe connection is made (the cord is 
plugged in), the id value of the destination object is assigned to 
the destination outlet 

I---1 


source destination 


Outlets are declared as: 


id anObject; 

You can use id as the type for any object; objects with id as their 
type are dynamicallytyped, meaning thatthe class of the object is 
determined at run time. You can statically type an object as a 
pointer to a class name; you can declare these objects as 
instance variables, but they are not outlets. What distinguishes 
outlets is their relationship to Interface Builder. 

Interface Builder can "recognize" outlets in code by their 
declarations, and it can initialize outlets. You usually set an 
outlet's value in Interface Builder by drawing connection lines 
between objects. There are ways other than outlets to reference 
objects in an application, but outlets and Interface Builder's 
facility for initializing them are a great convenience. 





An outlet is an instance variable that identifies an object. 



You can communicate with other objects in an application by 
sending messages to outlets. 


An outlet can reference any object in an application: user- 
interface objects such as text fields and buttons, windows and 
panels, instances of custom classes, and even the application 
object itself. 
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Target/Action in Interface Builder—What's Going On 

As you'll soon find out, you can view (and complete) target/action 
connections in Interface Builder's Connections inspector. This 
inspector is easy to use, but the relation of target and action in it 
might not be apparent First, target is an outlet of a cellobjectthat 
identifies the recipient of an action message. Well (you say) 
what's a cell object and what does it have to do with a button?— 
that's what I'm making the connection from. 

One or more cell objects are always associated with a control 
object (that is, an object inheriting from NSControl, such as a 
button). Control objects "drive" the invocation of action methods, 
but they get the target and action from a cell. NSActionCell 
defines the target and action outlets, and most kinds of cells in the 
Application Kit inherit these outlets. 



For example, when a user clicks the Convert button of Currency 
Converter, the button gets the required information from its cell 
and sends the message convert to the target outlet, which is an 
instance of your custom class ConverterController. 

In the Actions column of the Connections inspector are all action 
methods defined by the class of the target object and known by 
Interface Builder. Interface Builder identifies action methods 
because their declarations follow the syntax: 

- (void)doThis:(id)sender; 

It looks in particular for the argument sender. 


Which Direction to Connect? 

Usually the outlets and actions that you connect belong to a 
custom subclass of NSObject Forthese occasions, you need only 
follow a couple simple rules to know which way to draw a 
connection line in Interface Builder 

• To make an action connection, draw a line to the custom 
instance from a control object in the user interface, such as a 
button ora text field. 

• To make an outlet connection, draw a line from the custom 
instance to another object in the application. 

Another way to clarify connections is to consider who needs to 
find whom. With outlets, the custom object needs to find some 
other object, so the connection is from the custom object to the 
other object With actions, the control object needs to find the 
custom object, so the connection is from the control object 

These are only rules of thumb for the common case, and do not 
apply in all circumstances. For instance, many OpenStep objects 
have a delegate outlet; to connect these, you draw a connection 
line from the OpenStep object to your custom object 
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l Generate an instance of the 
class. 

In the Classes display, select the 
ConverterController class. 

Choose the Instantiate command 
from the Operations pull-down 
menu. 


Connetfing ConverterController to the Interface 

As the final step of defining a class in Interface Builder, you create an instance 
of your class and connect its outlets and actions. 
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Click the class name to collapse outlets and 
actions. If they are already collapsed, make 
sure your subclass is selected. 


Choose this command to generate an 
instance of your custom class. 


Note: The Instantiate command does not generate a true instance of 
ConverterController, but creates a stand-in object used for establishing 
connections. When the nib file’s contents are unarchived, Interface Builder will 
create true instances of these classes and use the proxy objects to establish the 
outlet and action connections. 

When you instantiate a class (that is, create an instance of it), Interface Builder 
switches to the Instances display and highlights the new instance, which is 
named after the class. 
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Now you can connect this ConverterController object to the user interface. By 
connecting it to specific objects in the interface, you initialize your outlets. 
ConverterController will use these outlets to get and set values in the interface. 
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5 Connect the custom class to the 
interface via its outlets. 

In the Instances display of the nib 
file window, Control-drag a 
connection line from the 
ConverterController instance to 
the first text field. 

Whenthefield is outlined in black, 
release the mouse button. 
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Control-drag from an object with defined 
outlets )often an instance of a custom 
class). 


When a black line encloses an object, it will 
be selected as the destination object of the 
connection if you release the mouse 
button. 


Interface Builder brings up the Connections display of the Inspector panel. This 
display shows the outlets you have defined for ConverterController. 


In the Connections display, select 
the outletthat corresponds to the 
first field (rateField). 

Click the Connect button. 

Following the same steps, 
connect ConverterController's 
dollarField and totalField outlets 
to the appropriate text fields. 
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Outlets of the destination object appear 
under this column of the Connections 
display. 


When you click Connect the connection 
appears here, including the class of the 
destination object. 


To receive action messages from the user interface—to be notified, for example, 
when users click a button—you must connect the control objects that emit those 
messages to CurrencyConverter. The procedure for connecting actions is similar 
to that for outlets, but with one major difference. When you connect an action, 
always start the connection line from a control object (such as a button, text field, 
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6 Connect the interface's controls 
to the custom class via its 
actions. 

Control-drag a connection line 
from the Convert button to the 
ConverterController instance in 
the nib file window. 

When the instance is outlned in 
black, release the mouse button.. 


In the Connections display, make 
sure target in the Outlets column 
is selected. 

Select convert: in the Actions 
column. 

Clickthe Connect button. 

Save the CurrencyConverter nib 
file (Document ► Save). 


or form) that sends an action message; you usually end the connection at an 
instance of your custom class. That instance is the target outlet of the control 
object. 
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The source object of an action connection 
must be a control object. 


When a black line encloses an object, it will 
be selected as the destination object of the 
connection if you release the mouse 
button. 


The Connections display of the Inspector panel shows the action methods you 
have specified for ConverterController. 



Connections ^ 


convert: 


NS Button Inspector 


Actions 


Outlets 


Connections 


If you had defined other actions for 
ConverterController, they would have 
appeared in this column. 


Interface Builder allows you to set these 
outlets directly for buttons. 


Make sure that you click here to establish 
the connection. 


You’ve finished defining the classes of Currency Converter—almost. 
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Before You Go On - 

Define the Converter Class: While connecting ConverterController’s outlets, you 
probably noticed that one outlet remains unconnected: converter. This outlet 
identifies the instance of the Converter class in the Currency Converter 
application, which doesn’t exist yet. 

Define the Converter class. This should be pretty easy because Converter, as 
you might recall, is a model class within the Model-View-Controller paradigm. 
Since instances of this type of class don’t communicate directly with the 
interface, there is no need for outlets or actions. Here are the steps to be 
completed: 

1. In the Classes display, make Converter a subclass of NSObject. 

2. Instantiate the Converter class. 

3. Make an outlet connection between ConverterController and Converter. 
When you are finished, save CurrencyConverter.nib. 


Optional Exercise - 

Text fields and action messages: The NSReturnsign image that you embedded earlier in 
the Convert button indicates that users can activate this button by pressing the 
Return key. In Currency Converter this key event occurs when the cursor is in 
a text field. Text fields are control objects just as buttons are; when the user 
presses the Return key and the cursor is in a text field, an action message is sent 
to a target object if the action is defined and the proper connection is made. 

Connect the second text field (that is, the one with the “Dollars to Convert” 
label) to the convert: action method of ConverterController. You won’t be 
disconnecting the prior action connection because multiple control objects in an 
interface can invoke the same action method. 
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Implementing the Classes of Currency Converter 


Interface Builder generates source code files from the (partial) class definitions 
you’ve made. These files are “skeletal,” in the sense that they contain little 
more than essential Objective-C directives and the class-definition information. 
You’ll usually need to supplement these files with your own code. 


1 In Interface Builder, generate 
header and implementation files. 

Go to the Classes display of the 
nib file window. 

Select the ConverterController 
class. 

Choose Create Files from the 
Operations pull-down menu. 
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Click here to bring up the Classes display. 


Make sure your class is selected before 
choosing Create Files. 


Interface Builder then displays two attention panels, one after the other: 


When a Create Files panel is 
displayed, click Yes. 

A second Create Files panel is 
displayed; click Yes again. 

Repeat for the Converter class. 

Save the nib file. 



Create Files 


Create 

/Net/seaport/homes/del aware/td on o/P roj e cts/C u rre n c 
yConverter/ConverterController.[hm]? 



Create Files 


Insert files ConverterController.[hm] in project? 


Click Yes to confirm that you want the 
header and implementation files for the 
class created. Interface Builder files have 
an extension of.h and implementation files 
an extension of.m. 


Click Yes to confirm that you want the 
source code files added to the project in 
Project Builder. If, for example, you wanted 
to add the files to another project, you 
would click No. 


Now we leave Interface Builder for this application. You’ll complete the 
application using Project Builder. 
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2 Examine an interface (header) 
file in Project Builder. 

Hide Interface Builder and 
activate Project Builder. 

Click Headers in the project 
browser. 

Select ConverterController.h. 



Project Builder imports the 
Application Kit header files, 
which import the Foundation 
header files. 

(#>import includes files only if 
they haven't already been 
included.) 


Interface definitions begin 
with @ interface and the class 
name. The superclass appears 
after the colon. 


Instance variables (here the 
outlets defined in Interface 
Builder) go between the 
braces. 

Method declarations follow the 
second brace. The declaration 
of the action method you 
specified in Interface Builder is 
inserted. The definition ends 
with @end. 


You can add instance variables or method declarations to a header file generated 
by Interface Builder. This is commonly done, but it isn’t necessary in 
ConverterController’s case. But we do need to add a method to the Converter 
class that the ConverterController object can invoke to get the result of the 
computation. Let’s start with by declaring the method in Converter.!!. 


3 Add a method declaration. 

Select Converter.!! in the project 
browser. 

Insert a declaration for 
convertAmount:byRate:. 


#import <AppKit/AppKit.h> 

#import <Foundation/Foundation.h> 

©interface Converter:NSObject 
{ 

} 


- (float)convertAmount:(float)rate byRate:(float)amt; 


©end 


This declaration states that convertAmount:byRate: takes two arguments of type float, 
and returns a float value. When parts of a method name have colons, such as 
convertAmount: and byRate:, they are keywords which introduce arguments. (These 
are keywords in a sense different from keywords in the C language.) Most 
method declarations begin with a dash (-), followed by a space. 

Now you need to update both implementation files. First examine Converter.m. 
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4 Examine an implementation file. 

Click Classes in the project 
browser. 

Select Converter.m. 


5 Implement the classes. 

Type the code at right between 
©implementation and ©end in 
Converter.m. 


Select ConverterController.m in 
the project browser. 

Update the convert: method as 
shown by the example. 

Import Converter.!!. 
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The associated header file is 
imported automatically. 


Class implementations begin 
with @implementation and 
the class name. 


Put implementations of 
methods between 
@implementation and @end. 


For this class, implement the method declared in Converter.!!. Between 
©implementation Converter and @end add the following code: 


- (float)convertAmount:(float)amt byRate:{float)rate 

{ 

return (amt * rate); 

} 


The method simply multiplies the two arguments and returns the result. Simple 
enough. Next update the “empty” implementation of the convert: method that 
Interface Builder generated. 

- (void)convert:(id)sender 

{ 

float rate, amt, total; 

amt = [dollarField floatValue]; /* 1 */ 

rate = [rateField floatValue]; 

total - [converter convertAmount:amt byRateirate]; /* 2 */ 
[totalField setFloatValue:total]; /* 3 */ 

[rateField selectText:self]; /* 4 */ 

} 


The convert: method does the following: 

1. Gets the floating-point values typed into the rate and dollar-amount fields 
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6 Implement the awakeFromNib 
method. 

Type the code shown at right. 


2. Invokes the convertAmount:byRate: method and gets the returned value. 

3. Uses setFloatValue: to write the returned value in the Amount in Other 
Currency text field (totalField). 

4. Sends selectText: to the rate field; this puts the cursor in the rate field so the 
user begin another calculation. 

Be sure to #import "Converter.h” —ConverterController invokes a method defined 
in the Converter class, so it needs to be aware of the method’s declaration. 

Before You Go On - 

Each line of the convert: method shown above, excluding the declaration offloats, 
is a message. The “word” on the left side of a message expression identifies the 
object receiving the message ( called the “receiver”). These objects are 
identified by the outlets you defined and connected. After the receiver comes 
the name of the method that the sending object (called the “sender”) wants to 
invoke. Messages often result in values being returned; in the above example, 
the local variables rate, amt, and total hold these values. 


Before you build the project, add a small bit of code to ConverterController.m that 
will make life a little easier for your users. When the application starts up, you 
want Currency Converter’s window to be selected and the cursor to be in the 
Exchange Rate per $1 field. We can do this only after the nib file is unarchived, 
which establishes the connection to the text field rateField. To enable set-up 
operations like this, awakeFromNib is sent to all objects when unarchiving 
concludes. Implement this method to take appropriate action. 


- (void)awakeFromNib 
{ 

[rateField selectText:self]; /* 1 */ 

[[rateField window] makeKeyAndOrderFront:self]; /* 2 */ 

} 


1. You’ve seen the selectText: message before, in the convert: implementation; it 
selects the text in the text field that receives the message, inserting the cursor 
if there is no text. 

2. The makeKeyAndOrderFront: message does as it says: It makes the receiving 
window the key window and puts it before all other windows on the screen. 
This message also nests another message; [rateField window] returns the window 
to which the text field belongs, and the makeKeyAndOrderFront: method is then 
sent to this returned object. 
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The Objective-C language is a superset of ANSI C with special 
syntax and run-time extensions that make object-oriented 
programming possible. Objective-C syntax is uncomplicated, but 
powerful in its simplicity. You can mix standard C and even C++ 
code with Objective-C code. 

The following summarizes some of the more basic aspects of the 
language. See Object-Oriented Programming and the Objective-C 
Language for complete details. Also, see "Object-Oriented 
Programming" in the appendix for explanations of terms that are 
italicized. 

Declarations 

• Dynamically type objects by declaring them as id: 

id myObject; 

Since the class of dynamically typed objects is resolved at run 
time, you can refer to them in your code without knowing 
beforehand what class they belong to. Type outlets in this way 
as well as objects that are likely to be involved in polymorphism 
and dynamic binding. 

• Statically type objects as a pointerto a class: 

NSString *mystring; 

You statically type objects to obtain better compile-time type 
checking and to make code easierto understand. 

• Declarations of instance methods begin with a minus sign (-) 
and, for class methods, with a plus sign (+): 

- (NSString *)countryName; 

+ (NSDate *)calendarDate; 

• Putthetype of value returned by a method in parentheses 
between the minus sign (or plus sign) and the beginning of the 
method name. (See above example.) Methods returning no 
explicit type are assumed to return id. 

• Method argument types are in parentheses and go between 
the argument's keyword and the argument itself: 

- initWithName: (NSString *) name 

andType:(int)type; 

Be sure to terminate all declarations with a semicolon. 

• By default, the scope of an instance variable is protected, 
making that variable directly accessible only to objects of the 
class that declares it or of a subclass of that class. To make an 
instance variable private (accessible only within the declaring 
class), insert the ©private directive before the declaration. 


Messages and Method Implementations 

• Methods are procedures implemented by a classfor its objects 
(or, in the case of class methods, to provide functionality not 
tied to a particular instance). Methods can be public or private; 
public methods are declared in the class's header file (see 
above). Messages are invocations of an object's method that 
identify the method by name. 

• Message expressions consist of a variable identifying the 
receiving object followed by the name of the method you want 
to invoke; enclose the expression in brackets. 

[anObject doSomethingWithArg:this]; 
receiver method to invoke 
As in standard C, terminate statements with a semicolon. 

• Messages often get values returned from the invoked method; 
you must have a variable of the proper type to receive this 
value on the left side of an assignment. 

int result = [anObj calcTotal]; 

• You can nest message expressions inside other message 
expressions. This example gets the window of a form object 
and makes it the receiving object of another message. 

[[form window] makeKeyAndOrderFront:self]; 

• A method is structured like a function: After the full declaration 
of the method comes the body of the implementing code 
enclosed by braces. 

• Use nil to specify a null object; this is analogous to a null 
pointer. Note that some OpenStep methods do not accept nil 
objects as arguments. 

• A method can usefully refer to two implicit identifiers: seif and 
super. Both identify the object receiving a message, but they 
affect differently how the method implementation is located: 
self starts the search in the receiver's class whereas super 
starts the search in the receiver's superclass. Thus 

[super init]; 

causes the init method of the superclass to be invoked. 

• In methods you can directly access the instance variables of 
your class's instances. However, accessor methods are 
recommended instead of directaccess, exceptin cases where 
performance is of paramount importance. Chapter 4, "Travel 
Advisor Tutorial," describes accessor methods in greater 
detail. 
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Building the Currency Converter Project 


The Build process in Project Builder compiles and links the application guided 
by the information stored in the project’s makefiles. You must begin builds from 
the Project Build panel. 


1 Build the project. 

Save source code files and any 
changes to the project 

Clickthe Build button on the main 
window (icon at right). 

Clickthe Build button on the 
Project Build panel (same icon). 


You don’t have to maintain 
makefiles in Project Builder. It 
updates Makefile according to the 
variables specified through its 
user interface. You can customize 
the build process by modifying 
the Makefile.preamble and 
Makefile.postamble files. For 
more information on customizing 
these files, see OPENSTEP 
Development: Tools and Techniques 



When you click the Build button on the main window, the Project Build panel 
is displayed. 



9SDHHKE 
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Target app 

Status: CurreocyCom/erter.app—dutfcf succeeded 

\ ..... 


-.J! 


ydynamlc_obj/m£8WCurTencyCcnverter_main.o 

/bln/cc -g - Walt -pipe -O -dynamic -fh e-common -l/ProjectHeade r » .. 

-I7derlved_src -arch m68k -ObJC -sectcreate _JCON _Jiaader 

CurrencyConvertericonheader-segprol_ICONrr sectcreate_ICON app 

apptication.tjff-o yCurrancyConverter.app/CurrencyConverter.mBek 
ydynamlc_obim»68k/Converter.oydynamlc_obj/in66k/ConverterConlroll6r.o 
ydynamic jDbj/m68k/CuroncyConverteMnain.o -framework AppKIt 
-framework Foundation 

® /bin/Jn yCurrencyConverter.app/CurrencyConvert8rm68k 
CurrencyConvert8r.app/CurrencyConverter 


Build, Clean, and Build 
Options buttons. 


Build error browser. 


Detailed build results. 


When you click the Build button on the Project Build panel, the build process 
begins; Project Builder logs the build’s progress in the lower split view. When 
Project Builder finishes—and encounters no errors along the way—it displays 
“Build succeeded.” 


Of course, rare is the project that is flawless from the start. Project Builder is 
likely to catch some errors when you first build your project. To see the error¬ 
checking features of Project Builder, introduce a mistake into the code. 
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What Happens When You Build an Application 
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By clicking the Build button in Project Builder, 
you run the build tool. By default, the build tool is 
gnumake, but it can be any build utility that you 
specify as a project default in Project Builder. 
The build tool coordinates the compilation and 
linking processthat results in an executable file. 
It also performs other tasks needed to build an 
application. 

The build tool manages and updates files based 
on the dependencies and other information 
specified in the project's makefiles. Every 
application project has three makefiles: 
Makefile, Makefile.preantble, and 
Makefile.postamble. Makefile is maintained by 
Project Builder—don't edit it directly-—but you 
can modify the other two to customize your 
build. 

The build tool invokes the compiler tool cc, 
passing it the source codefiles of the project. 
Compilation of these files (Objective-C, C++, and 
standard C) produces machine-readable object 
files for the architecture (or architectures) 
specified for the build. It puts these files in an 
architecture-specific subdirectory of 
dynamic_obj. 

In the linking phase of the build, the build tool 
executes the link editor Id (via cc), passing it the 
libraries and frameworks to link against the 
object files. Frameworks and libraries contain 
precompiled code that can be used by any 
application. Linking integrates the code in 
libraries, frameworks, and object files to 
produce the application executable file.lf there 
are multiple architecture-specific object files, 
linking also combines these into a single "fat" 
executable. 

The build tool also copies nib files, sound, 
images, and other resources from the project to 
the appropriate localized or non-localized 
locations in the application wrapper. 



An application wrapper is a file package with an extension of 
".app". A file package is a directory that the Workspace 
Manager presents to users as a simple file; in other words, it 
hides the contents of the directory. The ".app" extension tells 


the Workspace Managerthatthe application wrapper 
contains an executable that can be run ("launched") by 
double-clicking. 
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2 Build the project after correcting 
errors. 

Delete a semicolon in the code, 
creating an error. 

Click the Build button on the 
Project Build panel. 

Click the error-notification line 
that appears in the build error 
browser (upper split view). 

Fix the error in the code. 

Re-build. 


CUrraicy Converts— 




Target app 

Stabs: CunoncyCormrter&pp--Build totted 
1 error 


Cony,site,mi 


^ Illegal statement missingafter*)* 


■U 


" To navigate to an 
error in a code file , 
click the line 
describing the error. 


Currency Converter — -/Projects 


* Making Cur 
I Exporting heac 
...tdr Currency! 
Done exportinj 
/bln/cc*g-Wai 
•Uderived_snc 
ydynarftlc.obp 
Converter.m:8: 
gnumakejt]:" 
gnumake: w (< 


IE 


IB 





r ' = * Converterm 



IClasses 


I Other Sources r- f, 
Interfaces 
Images r ] 

Other Resource r 
Subprojects r j 

▼IrnntextHetp r* 


SConverter.m 


■ ©Converter 


1-convertAmount.b 


•import 'Converter.h’ 
dimplementotion Converter 

- (floot>convertAoount.(float)aat byRote:(fIoat)rote 

czm&mziEsn. 


illegal statement: missing *;* alter *)* 


) 

dend 


Project Builder highlights the line that 
contains the error ,; _ 
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Context-Sensitive Application Help 

Project Builder and Interface Builder provide context-sensitive 
help on the details of their use. To activate context-sensitive help, 
Help-click a control, field, menu command, or other areas of the 
application. A small window appears that briefly describes the 
selected object. 

The Help key varies by computer architecture. Consult user 
documentation for the Help key on your machine. 


Info 


r-1 Font 


Document r 


Edit 


Text 


Bring to Front 


Bring to Front command 




.window. If one object fs hidden by anotheri.you can select one of the objects and execute.either 
■ command so that you can easily select and move the other: object.:: •::. x• •::: . 


Digital Librarian 

Digital Librarian is an application that quickly searches for a word 
(or other lexical unit) in an on-line manual (or other target) and 
lists the documents that contain the word. You click a listed item 
and the document is displayed at the point where the word 
occurs. The contents of documents are indexed, making 
searching very fast. 

OpenStep includes NextDeveloper.bshlf, a Digital Librarian 
bookshelf for developers in /NextLibrary/Bookshelves. This 
bookshelf contains most of the targets you are likely to want, and 
includes (asthetopmosttarget) instructions on creating your own 
bookshelf and customizing it to your needs. When you choose 
Help from Project Builder or Interface Builder, a Digital Librarian 
bookshelf is opened that contains the on-line version of 
OPENSTEP Development: Tools and Techniques . 







UNIX Manual Developer Header Files NextDeveloper 
Pages Release Notes Examples 



1 founci In Contents _d W£i2_d 




Developer Release Notes ; 


JO: CompilerTools.rtf 


You can find Digital Librarian as Librarian.app in /NextApps. 
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Project Builder 


Project Builder gives you several ways to get the information you 
need when developing an application. 

Project Find: The Project Find panel allows you to search for 
definitions of, and references to, classes, methods, functions, 
constants, and other symbols in your project Since it is based on 
project indexing, searching is quick and thorough and leads 
directly to the relevant code. See OPENSTEP Development: Tools 
and Techniquesfor a complete description of Project Find. 

Reference Documentation Lookup: If the results of a search using 
Project Find includes OpenStep symbols, you can easily get 
related reference documentation that describes that symbol. See 
"Finding Information Within Your Project" on page 94 for 
instructions on the use of this feature. 


Frameworks: Under Frameworks in the project browser, you can 
browse the header files related to OpenStep frameworks within 
Project Builder. The Application Kit and Foundation frameworks 
always are included by default for application projects. See 
chapter 5, "Where to Go From Flere," for a fuller description 



Interfaces r 


AppKitframewo t- 

Li 

Foundation^ r* 



Images r* 


Foundation.fra r> 

Foundation^ 


r 

Other Resourc f* 
Subprojects h 
Supporting File r 

" 


' 

NSAccounth h 
NSArchiver.h > 
NS Array, h H 



Context Help h 




NSAutorelease m 


7 

UMMes._. 

• 

: j 

Aj 

NSBundie.h h 


Frameworks t> 

' 


NSByteOrder.h r v 


Y 

Non Project Fil F ! 



La 

NSCharacterS fr 
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NeXT's Technical Documentation 

Most OpenStep programming documentation is located on-line in 
NeXTLibrary/Documentation/NextDev. The document files are in 
RTF format, so you can open them in Project Builder, Edit, or in 
most word processors. NeXT includes the following manuals 
under the /NextDev directory: 

Reference 

• API Reference Documentation (specifications of classes, 
protocols, functions, types, and constants). This 
documentation is divided among, and located in, the 
frameworks NeXT provides, except for information that is 
common to all frameworks (/Reference). 

• Development Tools Reference covering the compiler, the 
debugger, and othertools (Reference DevTools). 

• NeXT Assembler Manual 

Tasks and Concepts 

• Discovering OPENSTEP: A Developer Tutorial (this manual) 

• Object-Oriented Programming and the Objective-C Language 

• Topics in OPENSTEP Programming (concepts and 
programming procedures) 

• OPENSTEP Development: Tools and Techniques (a task- 
oriented approach to using the development tools) 

• OPENSTEP Conversion Guide (step-by-step instructions for 
converting 3.x NEXTSTEP applications to run on OPENSTEP 4.0. 

The /NextDev directory also includes release notes. It also 
contains documentation on the following products, if they're 
installed: Enterprise Objects Framework, Distributed Objects 
(DO), Portable Distributed Objects (PDO). 

See chapters, "Whereto Go From Here," for more information on 
NeXT's technical publications. 
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Run Currency Converter 


Congratulations. You’ve just created your first OpenStep application. Find 
CurrencyConverter.app in the Workspace, launch it, and try it out. Enter some rates 
and dollar amounts and click Convert. Also, select the text in a field and choose 
the Services menu; this menu now lists the other applications that can do 
something with the selected text. 


You can use Project Builder’s 
graphical debugger or gdb to track 
bugs down. See “Using the 
Graphical Debugger” on page 
104 for an overview of the 
graphical debugger. 


Of course, the more complex an application is, the more thoroughly you will 
need to test it. You might discover errors or shortcomings that necessitate a 
change in overall design, in the interface, in a custom class definition, or in the 
implementation of methods and functions. 

Although it’s a simple application, Currency Converter still introduced you to 
many of the concepts, tools, and skills you’ll need to develop OpenStep 
applications. Let’s review what you’ve learned: 






Composing a graphical user interface (GUI) with Interface Builder 
Testing the interface 

Designing an application using the Model-View-Controller paradigm 
Specifying a class’s outlets and actions 

Connecting the class instance to the interface via its outlets and actions 

Class implementation basics 

Building an application and error resolution 


Optional Exercise - 

Nesting Messages:You can nest message expressions; in other words, you can use 
the value returned by a message as the receiver of another message or as a 
message argument. It is thus possible to rewrite the first three messages of the 
ConverterController’s convert: method as one statement: 


total = [converter convertAmount:[dollarsField floatValue] 
byRate:[rateField floatValue]]; 

It is possible to go even further. Try to incorporate the fourth message ([totalField 
setFIoatValue:total]) of the convert: method into the above statement. 
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In this chapter you create Travel Advisor, an application that is considerably 
more complex than the Currency Converter application you built in the first 
tutorial. Travel Advisor is a forms-based application used for entering, viewing, 
and maintaining records on countries that the user travels to. Users enter a 
country name and information associated with that country. When they click 
Add, the country appears in the table below the country name. They can select 
countries in the table, and the information on that country appears in the forms. 
The application also performs temperature and currency conversions. 


'Travel Advisor; 


Country: | Australia 


Australia 


France 

Germany 


Motes and itinerary for Australia 


Lv 6/25/95 1 1:35 SFO Quantas 
Arr Sydney 6/27 4:14 AM 
Meeting John Croften, Sr. VP, 
Bank of Australia, 4th Floor, 2 PM 
Bring presentation slides 


4L 


Logistics - 


Airports:| Sydney International 


Airlines:| Quantas 


Transportation:! Tax i $25 Aus downtown Sydney 


Hotels: Sydney Hi It on $ 7 5 Aus/night 


Other - 


Currency:! A us. Dollar Rate:|o 715 per$i 
Languages:! English 

Pi English widely spoken 


Conversions 


Dollars: 1 5000.00 j; Local: [3576.50. 
Celsius: lo.oo Farenheit: |o 


'Convert I 


Convert 


Add 


ri-i-.: 


m 


Delete 


Clear 


This chapter presents a lot of information on OpenStep programming. Among 
other things, you’ll learn how to: 


Collection objects allow you to 
store, organize, and access data in 
different ways. For more 
information, see “The Collection 
Classes” on page 74. 

String objects represent textual 
strings in various encodings. See 
page 82 for more information. 


• Use several new objects on Interface Builder’s palettes. 

• Assign an icon to an application. 

• Print the contents of a view. 

• Use collection objects (NSArray and NSDictionary). 

• Use string objects (NSString). 

• Archive and unarchive object data. 

• Format and validate field contents. 

• Manage events through delegation. 

• Quickly find information related to your project. 

• Use Project Builder’s graphical debugger. 


You can find the TravelAdvisor 
project in the AppKit subdirectory 

of /NextDeveloper/Examples. 


Perhaps most interestingly, you will reuse the Converter class you implemented 
in the previous tutorial. 
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Creating the Travel Advisor Interface 


1 Create the application project. 

Start Project Builder. 

Choose New from the Project 
menu. 

Name the application 
"TravelAdvisor." 


2 Open the application's nib file. 

Click Interfaces in the project 
browser, select 
TravelAdvisor.nib, and double¬ 
click its icon. 

3 Customize the application's 
window. 

Resize the window, using the 
example at right as a guide. 

In the Attributes display of the 
Inspector panel, entitle the 
window "Travel Advisor." 

Turn off the resize bar. 


You should be familiar with many of the objects on the Travel Advisor interface 
because you’ve encountered them in the Currency Converter tutorial. The 
following illustration points out the objects that are new to you in this tutorial. 



Scroll view 
(containing an 
NSText object) 


Table view 


Image view Switch (button) 


Form 


Groups 

(Boxes) 


The following pages describe the purpose of each new object found on 
Interface Builder’s palettes and explain how to set these objects up for Travel 
Advisor. Before getting to these new objects, start with the familiar ones: 
buttons and text fields. 
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4 Put the text fields, labels, and 

buttons on the window. 

Position, re-size, and initialize the 
objects as shown. 



Be sure this label 
contains enough 
"padding" for the 
longest country 
name. 


Drag the Switch 
object from the 
Views palette and 
drop here. 


Set up the switch. 


You might think the “English widely spoken” object is a new kind of object. 
It’s actually a button, a special style of button called a switch. 


| jJEnglish widely spoken 




. Double-click to select text, then type new label. 


Click to set the initial state of this toggled button (no checkmark). 


Varieties of Buttons 

If in Interface Builder you select the "English 
widely spoken" switch and bring up the 
Attributes inspector, you can see that the 
switch is a button set up in a special way. 

Buttons are two-state control objects. They 
are either off or on, and this state can be set by 
the user or programmatically (setState:). For 
certain types of buttons (especially standard 
buttons like Currency Converter's Convert 
button), when the state is switched, the button 
sends an action message to a target object 
Toggle-type buttons—such as switches and 
radio buttons—visually reflect their state. 
Applications can learn of this state with the 
state message. You can make your own 
buttons, associating icons and titles with a 
button's off and on states, and positioning title 
and icon relative to each other. 




Attributes ~*j] 

I ~ .... . • 

' ____ 

Title: j English widely spoken 

| Alt. Title:] 

icon: j NS S witc h 

| Alt Icon:] NSHighlightedSwitch 
Sound:] 


Tag: K~~ Key: [ 


, Type 

Toggle 

— Alignment — 

|l* llRlMl 


- Icon Position -r 

□ 

Bordered 

Transparent^ 

Continuous 

Disabled^] 

Selected 

-□ — 

j— Pixels Inset r-? 
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5 Place a form on the interface and 
prepare it. 

Drag the form object from the 
Views palette. 


Increase the size of the form's 
fields by dragging the middle 
resize handle sideways. 

Create two more form fields by 
Alternate-dragging the bottom- 
middle resize handle downward, 


Rename the field labels. 


Construct the “Logistics” section of the interface using a form object. 



irrency:! It Plate: | j per$l 


Views IX 


Is 

3 EH 

]ffl 

B 

_ | mad*!**. 
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r II 
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: QRadto 
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m © 


> Drag to lengthen the fields. 


Field i[^ 
FietdC 

ml 

Fiellf 


~Tr 


As you Alternate-drag, new form fields 
appear underneath the cursor. 


r 

Airports 

Airlines 

Transportation: 

1 1 

1 

r - " ~ 1 

iF'e'* 1 ’ i 



Double-click to select label text. 

Type the new label text and click outside 
the form to set the text. 


More About Forms 

Forms are labelled fields bound vertically in a 
matrix. The fields are the same size and each 
label is to the left of its field. Forms are ideal 
objects for applications that display and 
capture multiple rows of data, as do many 
corporate client-server applications. 

The editable fields in a form are actually cells 
that you programmatically identify through 
zero-based indexing; the first cell is at index 
0 ofthe matrix,the second cell atindex 1, and 
so on. NSForm defines the behavior of forms; 
individual cells are instances of NSFormCell. 
Access these cells with NSForm's 
cellAtlndex: method. 




Form Attributes 

In addition to the obvious controls in the 
Forms inspector, there's the "Cell tags = 
positions" attribute. Switching this on 
assigns tags to each NSFormCell that 
correspond to the cells' indices. (A tag is a 
number assigned to an object that is used to 
idenitfy and access that object. You'll use 
tags extensively in the next tutorial.) 

The Scrollable option, turned on by default, 
enables the usertotype long entries in fields, 
scrolling contents to the left as characters 
are entered. 
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6 Group the objects on the 
interface. 

Select the two Convert buttons 
and the Dollars, Local, Celsius, 
Fahrenheit labels and text fields. 

Choose Format ► Group ► Group 
in Box. 

Double-click "Title" to select it. 

Choose Format ► Font ► Bold to 
make the title boldface. 

Rename "Title" to "Conversions." 

Repeat forthe next two groups: 
"Logistics" and "Other." 


To make titled sections of the fields, forms, and buttons on the Travel Advisor 
interface, group selected objects. By grouping them, you put them in a box. 


*jjj Dojp^ l "y' Scorwert |r 
jcel|iu$:J * • 5 f arej he it J * » •Cor w erl | 


To select the objects as a group, drag 
a selection rectangle around them or 
Shift-click each object. (To make a 
selection rectangle, start dragging from 
an empty spot on the window.) 


1 


" • -— - w 


Dollars: | ||- Local:f / 

! ?: Convert 11 

j 

\ Celsius: f |, Farenheit:! if; 

1;ConvertT 

jj 

----—..a- 


After you choose the Group in Box 
command, the objects are enclosed by 
a titled box. 


Boxes are a useful way to organize and name sections of an interface. In 
Interface Builder you can move, copy, paste, and do other operations with the 
box as a unit. For Travel Advisor, you don’t need to change the default box 
attributes. 


Before You Go On - 

Programmatically, the box is the superview of all of its grouped objects. (A view, 
simply put, is any object visible on a window.) A superview encloses its subviews 
and is the next in line to respond to user actions if none of its subviews cannot 
handle them. 


The scroll view on the Data Views palette encloses a text object (an instance of 
NSText). This object allows users to enter, edit, and format text with minimal 
programmatic involvement on your part. 
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7 Put the scroll view on the 
window and resize it. 

Drag the scroll view from the 
DataViews palette and drop it on 
the lower-left corner of the 
window. 

Resize the scroll view.. 



Country: [ 


Transports! 


Notes and Itinerary for 


Conversions 


Convert [ 


Dollars; 


Convert 


Celsius: 


Farenheit: 


Delete 


!! Clear 


Travel Advisor 



IHHUEl 

0_J 

IMP! 

- 

n 

Td 


(- i * 


You don’t need to change any of the default attributes of the scroll view (but you 
might want to look at the attributes you can set, if you’re curious). 

Next, add a table view for displaying the list of countries. 




More About Table Views 




A table view is an object for displaying and editing tabular data. 
Often that data consists of a set of related records, with rows for 
individual records and columns for the common fields (attributes) 
of those records, Table views are ideal for applications that have 
a database component, such as Enterprise Objects Framework 
applications. 

The table view on Interface Builder's TabulationViews palette is 
actually several objects, bound together in a scroll view. Inside 
the scroll view is an instance of NSTableView in which data is 
displayed and edited. At the top of the table view is an 
NSTableHeaderView object, which contains one or more column 
headers (instance of NSTableColumn). 


Later in this tutorial you will learn some basic techniques for 
accessing and managing the data in a table view. Here's a quick 
preview of the essential pieces: 

• Data source. The data source is any object in your application 
that supplies the NSTableView with data. The elements of data 
(usually records) must be identifiable through zero-based 
indexing. The data source must implement some or all of the 
methods of the NSTableDataSources informal protocol. 

• Column identifier. Each column (NSTableColumn) of a table 
view has an identifier associated with it, which can be either 
an NSString or a number. You use the identifier as a key to 
obtain the value of a record field. 




Scroll view 
(NSScrollView) ~ 

J 


- NSTableView 


• Delegate methods. NSTableView sends several messages to 
its delegate, giving it the opportunity to control the appearance 
and accessibility of individual cells, and to validate or deny 
editing infields. 





AT" 
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8 Place and configure the table 
view. 

Drag the table view object from 
the TabulationViews palette. 

Resize the table view. 


• • , • • : T,; 




Ifei 


— 



Click to 
select the 
Tabulation 
Views 
palette. 


Set the title of the first column to 
"Countries." 


J 

Countries j 


: ■. NS \ V '' 

iiillipiliiiiiilll 



Double-click column twice (first to select the column, 
second to insert the cursor). Type " Countries" then click 
anywhere outside the column. 


Make the table header only one 
column. 



Countries 


When this cursor appears over the line separating 
columns, drag the line so that it's flush with the right 
edge. 


The other object on the TabulationViews palette is a browser ; It is just as suitable 
for the Travel Advisor application as a table view. Browsers are ideal for 
displaying hierarchically structured information (such as is found in the UNIX 
file system) as well as single-level views of data such as the list of countries in 
Travel Advisor. A table view can also handle single-column rows of data easily; 
it is used instead because it is designed for displaying and editing records from 
relational databases, something that Enterprise Objects Framework (EOF) 
programmers find very useful. 

To configure the table view, you must set attributes of two component objects: 
the NSTableView object and the NSTableColumn object. 
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Select the NSTableView by 
double-clicking the interior of the 
table view. 

Set the attributes as shown at 
right. 


Select the column by double¬ 
clicking once (if this inserts the 
cursor, click outside the column, 
then clickthe column once). 

Setthe NSTableColumn attributes 
as shown at right. 


NSTableView Inspector 


Attributes 






«* Selection - ~] 

I Allows Empty Selection | 

| Allows Multiple SelectiodjgJ ||' 

' Allows Column SelectiorQ ! 



■ 


lift* 


* Scrollers - 


I Vertical Vj HorizontalfJ 


Height: [ 


- Rows - 




16 


J 


...-. Options- 

Show Grid yj 
Allows Resizing £J 
Allows Reordering£j 


Since this is a single-column view and country names are 
of limited length, you need only the verticle scroller, in case 
there's no more countries that can be shown at once. 


Whether to show the grid is a matter of personal 
preference, but turn off resizing and reordering. The user 
shouldn't be able to affect the contents of the column 
directly. 


The Attributes display for NSTableView is the same as that for NSScrollView. 



The Travel Advisor window is nearly complete. For a decorative touch, you’re 
next going to add an image to the interface. 
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9 Add an image to the interface. 

Drag the image view onto the 
window, as shown at right. 

In Project Builder: 

Double-click Images in the 
project browser. 

In the Open panel, select the file 
Airline.eps from the 
/AppKit/TravelAdvisor 
subdirectory of 
/NextDeveloper/Examples 



Before You Go On - 

Sometimes buttons are the preferred objects for holding images—for instance 
when you want a different image for either state of a button. But when buttons 
are disabled, any image they display is dimmed. So for decorative images, use 
image views (NSImageView) instead of buttons. 

When you drop a sound or image over a button or image view, it is added to the 
nib file. When you add an image or a sound to a nib file, Interface Builder asks 
if you also want to add the resource to the project. Nib files are localized and 
their resources are only accessible when the nib file has been loaded. Resources 
that are associated with a project can be localized and are always accessible. 


In the Attributes inspector for the 
image view, type the name of the 
image and set the NSImageView 
attributes. 

Make the image view (and the 
enclosed image) small enough to 
fit between the title bar and the 
Logistics group. 

Add a "velocity" line behind the 
airplane. 



Enter the name of the image file, minus the extension. 
The image can be in TIFF of EPS format, and must be 
part of the project 

You can also add an image by dragging it from the 
Images display of the nib file window and dropping it 
over the image view. 


The border of the image should not be visible. 


Since the image is larger than the image view, have it 
scale proportionally. 


Uncheck if you don't want users to affect the image in 
any way. 


69 











Chapter 3 


Travel Advisor Tutorial 


10 Add commandsto the main menu. 

Select the Menus palette. 

Drag the Item command and drop 
it between Edit and Services. 

Change "Item" to "Print Notes...". 

Drag the Submenu item and drop 
it between Info and Edit. 

Double-click Submenu to select 
the item text; change the name to 
"Records". 

Add three Items to the Records 
submenu (making four 
altogether). 

Change the command names to 
those shown at right. 

Add key equivalents to the right of 
the last two commands. 


Tip: To make the “velocity” line behind the airplane, make a title-less black box 
with a vertical offset of zero, and run the top and bottom lines together. 

Travel Advisor’s main menu has a submenu and a command that do not come 
ready-made on the Menus palette. You use the Submenu and the Item cells to 
create customized submenus and menu commands, respectively. 



TravelArtviso | X 

Record | X 

- Double-click the area to the riaht of the command and tvoe a letter. 

Info' ■" V 

Add Record 

Record r 

Delete Record 

Edit ' '6 

iiNexf Record h 

PrintNotes... : 

Prior Record— f- 

Windows ' ; T -1 

This letter is the Command key equivalent to teh menu command 
(Command-rhere because Command-p is often reserved for a print 
command). 

Services W-B 

Hide h 

iQuitl' ! T : : ' q 


Three dots after a menu command indicates that the command opens a panel: 
“Print Notes...” means that clicking this command displays the Print panel. 

You can now connect many of the objects on the Travel Advisor interface 
through outlets and actions defined by the Application Kit. As you might recall, 
text fields have a nextKeyView outlet that you connect so that users can tab from 
field to field. Forms also have a nextKeyView outlet for tabbing. (The fields within 
a form are already interconnected, so you don’t need to connect them.) 
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11 Connect Application Kit outlets 
for inter-field tabbing and 
printing. 

In top-to-bottom sequence, 
connect the fields and the form 
through their nextKeyView 
outlets. 

When you reach the Languages 
field, connect it with the Country 
field, making a loop. 


Travel Advisor 


Country: 



Holes and Itinerary for 


Airlines; [_ 
[ | Transportation;! 
Hotels:! 




Other 


(rcnniJI I J 

When a gray line borders the form, it is selected. 
Release the mouse button and set the nextkeyview 
outlet connection. 


The Application Kit also has “pre-set” actions that you can connect your 
application to. The NSText object in the scroll view can print its contents as can 
all objects that inherit from NSView. To take advantage of this capability, “hook 
up” the menu command with the NSText action method for printing. 


Connect the Print Notes menu 
command to the text object in the 
scroll view. 

Select the print: action method in 
the Connections display of the 
Inspector panel. 

Clickthe Connect button in the 
Inspector's Connection display. 



Make sure the text 
object (the white 
rectangle) is 
selected and not the 
scroll view that 
encloses it. 


The final step in crafting the Travel Advisor interface has nothing to do with the 
main window, but with what users see of your application when they encounter 
it in the File Manager: the application’s icon. 
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12 Add the application icon. 

In Project Builder: 

Open the Project Inspector. 

Goto the Project Attributes 
display of the inspector. 

Click in the Application Icon field. 

In File Manager 

Locate TravelAdvisor.tiff in the 
/AppKit/TravelAdvisor 
subdirectory of 
/NextDeveloper/Examples. 

Drag TravelAdvisor.tiff into the 
icon well in the Project Attributes 
display. 



Projects IntroNSProgra... PubsDev 


Travet Ad visor — Project Inspector joiX 


Project Attributes 


-WetPalntapp TPCalendar.p. 


Project Name:jTravejAdyi$or 
Language:) English 
Application Class:] NSApplication 
Main Nib FH as |~T rave I A d viso r 


Advisor 


Application & Document Icon, 


ostami 


Remove Row 




/ 

isor.tiff j 


: \ 

m 


niiiiiiii i iwrt m$\ 


Applcon 

TravelAdvisoMiff | 

: 


\0l\. .. ■ 

T:; 


1111 i 1% f HM 



■ ■■■:'■ ' •; H 



/ 


Make sure the cursor is in 
this field before dragging. 

After you drag the image 
into the well, the icon is 
displayed in the well and 
the image file is 
automatically added to the 
project 


13 Test the interface. You’re finished with the Travel Advisor interface. Test it by choosing Test 

Interface from Interface Builder’s Document menu.Try the following: 

• Press the Tab key repeatedly. Notice how the cursor jumps between the 
fields of the form, and how it loops from the Languages field to the Country 
field. Press Shift-Tab to make the cursor go in the reverse direction. 

• Enter some text in the scroll view, then click the Print Notes menu item. The 
print panel is displayed. Print the text object’s contents. 

• Also in the scroll view, press the Return key repeatedly until a slider appears 
in the scroller. 
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The Design of Travel Advisor 

Travel Advisor is much like Currency Converter in its basic design. Like 
Currency Converter, it’s based on the Model-View-Controller paradigm. A 
controller object (TAController) manages a user interface comprised of 
Application Kit objects. Also as before, the controller sends a message to the 
Converter object to get the result of a computation. In other words, the 
Converter object is reused. 



Travel Advisor’s view objects, in terms of Model-View-Controller, are all off-the- 
palette Application Kit objects, so the following discussion concentrates on 
those parts of the design distinctive to Travel Advisor. 

Model Objects 

Travel Advisor’s design is more interesting and dynamic than Currency 
Converter’s because it must display a unique set of data depending on the 
country the user selects. To make this possible, the data for each country is 
stored in a Country object. These objects encapsulate data on a country (in a 
sense, they’re like records in a relational database). The application can manage 
potentially hundreds of these objects, tracking each without recourse to a 
“hardwired” connection. 

Another model object in the application is the instance of the Converter class. 
This instance does not hold any data, but does provide some specialized 
behavior. 
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Controller 

The controller object for the application is TAController. Like all controller 
objects, TAController is responsible for mediating the flow of data between the 
user interface (the View part of the paradigm) and the model objects that 
encapsulate that data: the Country objects. Based on user choices in the 
interface, TAController can find and display the requested Country object; it 
can also save changes made by users to the appropriate Country object. 

What makes this possible is an NSDictionary object (called a dictionary from 
here on). A dictionary is a container that stores objects and permits their retrieval 
through key-value associations. The key is some identifier paired with an object 
in the dictionary (the object often holds the identifier as one of its instance 
variables). To get the object, you send a message to the dictionary using the key 
as an argument (objectForKey:). 

NSColor *aColor = [aDictionary objectForKey:@"BackgroundColor"]; 

A Country object holds the name of a country as an instance variable; this 
country name also functions as the dictionary key. When you store a Country 
object in the dictionary, you also store the country name (in the form of an 
NSString) as the object’s key. Later you retrieve the object by sending the 
dictionary the message objectForKey: with the country name as argument. 


The Collection Classes 


Several classes in OpenStep's Foundation Framework create 
objects whose purpose is to hold other objects. These collection 
classes are very useful. Instances of them can store and locate 
their contents through a number of mechanisms. 

• Arrays (NSArray) store and retrieve objects in an ordered 
fashion through zero-based indexing. 

• Dictionaries (NSDictionary) store and quickly retrieve objects 
using key/value pairs. For example, the key "red" might be 
associated with an NSColor object representing red. 

• Sets (NSSet) are unordered collections of distinct elements. 
Counted sets (NSCountedSet) are sets that can contain 
duplicate (non-distinct) elements;these duplicates are tracked 
through a counter. Use sets when the speed of membership¬ 
testing is important. 

The mutable versions of these classes allow you to add and 
remove objects programmatically after the collection object is 


created (see "Abstract Classes and Class Clusters" on page 101). 

Collection objects also provide a valuable way to store data. 
When you store (or archive) a collection object in the file system, 
its constituent objects are also stored. 


NSObject 


1 


NSSet 

I 

NSMutableSet 


NSArray NSDictionary 

i 

NSMutableArray 

NSMutableDictionary 

NSCountedSet 
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Sec “Implementing the 
TAControlIer Class” on page 90 
for a diagram that depicts the data 
relationships of TAControlIer as 
data source. See page 66 for more 
on NSTableView’s data source. 


See “Getting in on the Action: 
Delegation and Notification” on 
page 97 for more on delegation. 


Storing Data Source Information 

TAControlIer also manages the data source for the table view on the interface. 
It stores the keys of the dictionary in an array object (NSArray), sorted 
alphabetically. When the table view requests data, the TAControlIer “feeds” it 
the objects in the array. 

Creation of Country Objects 

Another important point of design is the manner in which the Country objects 
are created. Instead of Interface Builder creating them, the TAControlIer object 
creates Country objects in response to users clicking the Add button. 

Delegation and Notification 

An essential aspect of design not evident from the diagram are the roles 
delegation and notification play. The TAControlIer object is the delegate of the 
application object and thereby receives messages that enable it to manage the 
application, which includes tracking the edited status of Country objects, 
initiating object archival upon application termination, and setting up the 
application at launch time. 
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Defining the Classes of Travel Advisor 


Travel Advisor has three classes: Country, Converter, and TAController. Only 
TAController has outlets and actions. And, rather than defining the Converter 
class, you are simply going to add it to the project from the CurrencyConverter 
project and reuse it. 


1 Specify the Country and 
TAController classes. 

In Interface Builder, bring up the 
Classes display of the nib file 
window. 

For each class, select NSObject 
as the superclass. 

Choose Subclass from the 
Operations menu. 

Type the class name. 



O NSObject 

0 * * 

• : 'b Country 

!S e 

M FirstResponder 

j 11 m se© 

£ IBInspector >. 

• 1-0 «® 

0 IBPalette 

}ri# W if 

© NS Array 

Q © 

© NSC ell 

1 ’O'" 4© 

o Ws Cursor 

p © ©;j 




BISS 


mna 


iflmtantiate 


Subclass ^ P 


|1 Edit Class 


Read Fie 


Create Files' 


2 Specify TAController's outlets. 

Add the outlets shown in the nib 
file window at right. 



o TAController 


Celsius 


commentsFiej^r 

commerM^be! 

converter 

countryField 

currencyDollarsFleld 

currencylocalField 

currencyNameField 

currencyRateField 

englishSpokenSwitch 
fahrenheit 
ianguagesFjeld 
logisticsForm 
table View 


Travel Advisor.nib — ...elAdvisor/English.lproj □ X 


Through this outlet, the TAController 
object establishes a connection with 
the instance of the Converter class. 
You will reuse this class later in this 
section. 
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3 Specify TAController's actions. 

Define the action methods shown 
in the nib file window at right. 







Classes 


3 




. Actions, ; , . — 

addRecord : 

blankFieids: 

convertCelsius: 

convertCurrency: 

deleteRecord: 

handieTVCIick: 

nextRecord: 

. prevRecord; 


ill 



In OpenStep there are many ways to reuse objects through their classes. For 
example, subclassing an existing class to obtain slightly different behavior is one 
way to reuse the functionality of the superclass. Another way is to integrate an 
existing class—like the Converter class—into your project. 


4 Reuse the Converter class. 

In Interface Builder: 

Open CurrencyConverter.mil in 
the English.lproj subdirectory of 
the CurrencyConverter project 
directory. 

In the Classes display of the nib 
file window, select the Converter 
class. 

Choose Edit ► Copy. 

Select the nib file window for 

TravelAdvisor.nib. 

In the Classes display, select the 
superclass (NSObject). 

Choose Edit ► Paste. 

In Project Builder: 

Launch Project Builder. 

Select Classes in the project 
browser. 

Choose Project ►Add Files. 

In the Add Classes panel, 
navigate to the 
CurrencyConverter project 
directory and select Converter.m. 

When asked if you want to 
include the header file, click OK. 


Travel Ad visor.nib — ...elAdvisor/English.lproj n ‘ 


(f Instances Classes. Y Images- Sounds \ 


LEJ 


NSObject 


r 

O Converter 

0 


o FirstResponder 

0 

— 

d i B inspector \ 

1 0 


& SBP alette 

10 


Q NS Array 

0 


o NSCell 
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’ A 1 

O NSCursor 

Q 
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Make sure to select the 
superclass before pasting. 


TravelAdvisor-/Projects 


;| 

Classes r 

IT 
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Headers t> 
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:• 
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Ai 

Images ; r* 

./ 


▼J 

Other Resource> | 

s 




%: 1 


■ 

_ 



m 

Headers j. 
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When you add a 
class to a project, 
Project Builder 
adds the 

associated header 
file too. 

It copies both files 
from the source 
location. 
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5 Generate instances of the 
TAController and Converter 
classes. 


6 Connect the TAController 
instance to its outlets. 


Jraye!Atlvisor.nib — ...elAtivisor/English.lpro] i | □- | 


/ Instances } Classes \ Images \ Sounds \ 

•' . ' ' . " «! f 

m * 

j| aNSCursor 
o NSDictionary 
o NSFontManager 

FI 0 NSImage 

© NSResponder 
r 0 NSTableColumn 

Q Sound 

A | O TAController 

; ” ~ 

• ' o ©: | 

10 1 m 

(IIB'F - - 

* 

l 1 © : 5© 

J4 © 8 © < 

Tj\ /:■ ; 

'Operations r I 


Subclass J 


Instantiate ^ 

Edit Class 

Read File 

Create Files 


You don’t need to instantiate the Country class in the nib file because it is not 
involved in any outlet or action connections. TAController interacts behind the 
scenes with users as they manipulate the application’s interface. It therefore 
needs access to interface objects and to be made the target of action messages. 


Outlet 

Make Connection To 

Celsius 

Text field labelled "Celsius" 

commentsLabel 

Label that reads "Notes and Itinerary for" 

commentsField 

Text object within scroll view 

converter 

Instance of Converter class (cube in Instances display) 

countryField 

Text field labelled "Country" 

currencyDollarsField 

Text field labelled "Dollars" 

currencyLocalField 

Text field labelled "Local" 

currencyNameField 

Text field labelled "Currency" 

currencyRateField 

Text field labelled "Rate" 

englishSpokenSwitch 

Switch (button) labelled "English widely spoken" 

fahrenheit 

Text field labelled "Fahrenheit" 

languagesField 

Text field labelled "Languages" 

logisticsForm 

Form in group (box) labelled "Logistics"; the form is selected when a 
gray line borders it. 

tableView 

The area underneath the "Countries" column 
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Connect the TAController 
instance to the interface via its 
actions. 


Action 

Make Connection From 

addRecord: 

"Add" button 

blankFields: 

"Clear" button 

convertCelsius: 

"Convert" button to the right of the "Fahrenheit" field 

convertCurrency: 

"Convert" button to the right of the "Local" field 

deleteRecord: 

"Delete" button 

handleTVCIick: 

The table view(the area beneath the "Countries" column header) 

nextRecord: 

The "Next Record" menu command on the Records submenu 

prevRecord: 

The "Prior Record" menu command on the Records submenu 

switchChecked: 

The "English widely spoken" switch 


You can assign delegates 
programmatically or by using 
Interface Builder. For more 
information, see “Getting in on 
the Action: Delegation and 
Notification” on page 97. 


Before You Go On - 

You’re next going to connect objects through an outlet defined by several 
OpenStep classes. The value of this outlet, named delegate, is the id of a custom 
object. As the delegate of NSApp (the NSApplication object), TAController will 
receive messages from it as certain events happen. 


Checking Connections in Outline Mode 

The nib file window of Interface Builder gives you two modes in 
which to view the objects in a nib file and to make connections 
between those objects. So far you've been working in the icon 
mode of the Instances display, which pictorially represents 
objects such as windows and custom objects. 


Outline mode, as the phrase suggests, represents objects in a 
hierarchical list: an outline. The advantages of outline mode are 
that it represents all objects and graphically indicates the 
connections between them. You can connect objects through 
their outlets and actions in outline mode, as well as disconnect 
them by Control-clicking a connection line. 


^'insSnces^^ ^Classes' X?images Sounds A 


Click here for icon mode. - 

Click here for outline — 
mode. 

Connect objects in outline 
mode just as you do in icon 
mode: Control-drag a 
connection line between 
objects. 
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Click a right-pointing triangle to see connections 
out; click a left-pointing triangle to see 
connections into the object. 

Move the vertical line left or right to see details 
Ithis is a vertical split view). 

A connection is identified byname and icon for 
type (electrical outlet for outlet, cross-hairs for 
action) 
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Every application has a global NSApplication object (called NSApp) that 
coordinates events specific to the application. Among many other messages, 
NSApp sends a message to its delegate notifying it that the application is about 
to terminate. Later, you will implement TAController so that, when it receives 
this message, it archives (saves) the dictionary containing the Country objects. 


8 Connect the delegate outlet. 

Drag a connection line from File's 
Owner to the TAController object 

In the Connections display of the 
Inspector panel select delegate 
and click OK. 




[/Instances 


lasses 


.V Sounds .\ 


0 


It 


iie’sOwner First Responder: Main enu 

1 : ^-- 



Converter Travel Advisor TAController j 


__ii_i_ 


Notice that the direction of the 
connection is from the File's 
Owner object (which is the 
application object) to the 
TAController object 


9 Generate source code files for 
the TAController and Country 
classes. 

Save TravelAdvisor.nib. 

Select the class in the Classes 
display of the nib file window. 

Choose Create Files from the 
Operations pull-down menu. 


When you generate the header and implementation files for all classes of 
Currency Converter, you are finished with the Interface Builder portion of 
development. Be sure you save the nib file before you switch over to Project 
Builder. 


Files Owner 

Every nib file has one owner, represented by 
the File's Owner icon in a nib file window. The 
owner is an object, external to the nib file, 
that relays messages between the objects 
unarchived from the nib file and the other 
objects in your application. 

You can specify a file's owner in Interface 
Builder or programmatically, with 
NSBundle's loadNibNamed:owner:. The 
File's Owner icon for the main nib file always 
represents NSApp, the global NSApplication 
constant. The main nib file is automatically 
created when you create an application 
project; it is loaded in main() when an 
application is launched. 


Nib files otherthan the main nib file— 
auxiliary nib files —contain objects and 
resources that an application may load only 
when it needs them (for example, an Info 
panel). You must specify the owner of 
auxiliary nibbles. 

You can determine or set the class of the 
current nib file's owner in Interface Builder 
by selecting the File's Owner icon in the nib 
file window and then displaying the Custom 
Class inspector view. You'll get to practice 
this technique when you learn howto create 
multi-document applications in the next 
tutorial. 
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Just Add a Smock: Compiled and Dynamic Palettes 


A palette is a display on the Palettes window that holds one or 
more reusable objects. You can add these objects to your 
application's interface using the drag-and-drop technique. There 
are two types of palettes: dynamic and compiled (also called 
"static palettes"). To the user, they seem identical, but the 
differences are many. 

Static palettes are built as a project and have code defining their 
objects; dynamic palettes include no special code—they're 
unique configurations of objects found on static palettes. 
Consequently, static palettes must be compiled, but you can 
create dynamic palettes on the fly, without writing and compiling 
code. Objects on static palettes can have inspectors and editors, 
which dynamic-palette objects cannot. 

You usually create a static palette as a way to distribute your 
objects—and the logic informing these objects' behavior—to 
potential users. Many developers of commercial OpenStep 
objects make use of static palettes as a distribution media. 
Creating static palettes (and their inspectors and editors) is a 
more complex process than creating dynamic palettes, but the 
resulting product has more value added to it. 

Using Dynamic Palettes 

Dynamic palettes are a big convenience. You can save groups of 
objects, with or without their interconnections, to a dynamic 
palette at anytime. You can save dynamic palettes and store them 
in the file system, just as you do with the traditional compiled 
palette. You can remove the palette from the Palette viewer and, 
when you need it again, load it back into Interface Builder. 

To store objects on a dynamic palette: 

• Choose Tools ► Palettes ► New to create a blank palette. 


• Select objects singly or in groups on the interface or in the nib 
file window (either icon or outline mode) 

• Alternate-drag these objects and drop them on the blank 
palette. 


Alternate-drag to 
move objects 
onto palettes; to 
move objects 
around palettes, 
and to remove 
objects from 
palettes . 


You can use dynamic palettes to: 

• Store collections of often-used View objects configured with 
specific sizes and other attributes. For instance, you could 
have a "standard" text field of a certain length, font, and 
background color stored on a dynamic palete. 

• Hold windows and panels that are replicated in your projects 
(such as Info panels). 

• Store versions of interfaces. 

• Keep interconnected objects as a template that you can later 
use as-is or modify for particular circumstances. For instance, 
you could store a group of text fields and their delegate, or a set 
of controls and their connections to a controller object 

• Assist in prototyping and group work. For example, you could 
mail a palette file containing an interface to interested parties. 


Untitled j 
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Implementing the Country Class 


Although it has no outlets, the Country class defines a number of instance 
variables that correspond to the fields of Travel Advisor. 


1 Declare instance variables. 

In Project Builder, click Headers 
in the project browser,then select 

Country.h. 

Add the declarations shown 
between the braces at right. 


©interface Country : NSObject <NSCoding> 
{ 



NSString 

NSString 

NSString 

NSString 

NSString 

NSString 

BOOL 

NSString 

float 

NSString 


*name; 

*airports; 

^airlines; 

♦transportation; 

♦hotels; 

*languages; 
englishSpoken; 
*currencyName; 
currencyRate; 
♦comments; 


/* 1 */ 
/* 2 */ 


/* 3 ♦/ 


When a class adopts a protocol, it 
asserts that it implements the 
methods the protocol declares. 
Classes that archive or serialize 
their data must adopt the 
NSCoding protocol. See Object- 
Oriented Programming and the 
Objective-C Language for more on 
protocols. 


1. Declares that the Country class adopts the NSCoding protocol 

2. Explicitly types the instance variable as “a pointer to class NSString”—or a 
NSString object. See below for more about the NSString class. 

3. Declare non-object instance variables the same way you declare them in C 
programs. In this case, currencyRate is of type float. 


NSString: A String for All Countries 

NSString objects represent character strings. They're behind 
almost all text in an application,from labelsto spreadsheet entries 
to word-processing documents. NSStrings (or string objects) 
supplant that familiar C programming data type, char*. 

"But why?" you might be saying. "Why not stick with the tried and 
true?" By representing strings as objects, you confer on them all 
the advantages that belong to objects, such as persistency and 
distributability. Moreover, thanks to data encapsulation, string 
objects can use whatever encoding is needed andean choose the 
most efficient storage for themselves. 

The most important rationale for string objects is the role they play 
in internationalization . String objects contain Unicode characters 
ratherthanthe narrow range of characters afforded by the ASCII 


character set. Hence they can represent words in Chinese, 
Japanese, Arabic,and many other languages. 

The NSString and NSMutableString classes provide API to create 
static and dynamic strings, respectively, and to perform string 
operations such as substring searching, string comparison, and 
concatenation. 

None of this prevents you from using char * strings, and there are 
occasions where for performance or other reasons you should. 
However, the public interfaces of OpenStep classes now use 
string objects almost exclusively. A number of NSString methods 
enable you to convert string objects to char * strings and back 
again. 
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Country.h also declares a dozen or more methods. Most of these are accessor 
methods. Accessor methods fetch and set the values of instance variables. They 
are a critical part of an object’s interface. 


2 Declare methods. 

After the instance variables, add 
the declarations listed here. 


/* initializtion and de-allocation */ 

- (id)init; /* 1 */ 

- (void)dealloc; 

/* archiving and unarchiving */ 

- (void)encodeWithCoder:(NSCoder *)coder; /* 2 */ 

- (id)initWithCoder:(NSCoder *)coder; 

/* accessor methods */ 

- (NSString *)name; /* 3 */ 

- (void)setName:(NSString *)str; 

- (NSString *)airports; 

- (void)setAirports:(NSString *)str; 

- (NSString *)airlines; 

- (void)setAirlines:(NSString *)str; 

/* ...other accessor method declarations follow... */ 


1. Object initialization and deallocation. In OpenStep you usually create an object by 
allocating it (alloc) and then initializing it (init or init... variant): 

Country *aCountry = [[Country alloc] init]; 

When Country’s init method is invoked, it initializes its instance variables to 
known values and completes other start-up tasks. Similarly, when an object 
is deallocated, its dealloc method is invoked, giving it the opportunity to 
release objects it’s created, free malloc’d memory, and so on. You’ll learn more 
about init and dealloc shortly. 

2. Object archiving and unarchiving. The encodeWithCoder: declaration indicates that 
objects of this class are to be archived. Archiving encodes an object’s class and 
state (typically instance variables) in a file that is often stored within the 
application wrapper (that is, the “hidden” application directory). 
Unarchiving, through initWithCoder:, reads the encoded class and state data and 
restores the object to its previous state. There’s more on this topic in the 
following pages. 

3. Accessor methods. The declaration for accessor methods that return values is, by 
convention, the name of the instance variable preceded by the type of the 
returned value in parentheses. Accessor methods that set the value of instance 
variables begin with “set” prepended to the name of the instance variable 
(initial letter capitalized). The “set” method’s argument takes the type of the 
instance variable and the method itself returns void. 
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The Foundation Framework: Capabilities, Concepts, and Paradigms 


4 PM \ 


The Foundation Framework consists of a base layer of classes 
that specify fundamental object behavior plus a number of utility 
classes. It also introduces several paradigms that define 
functionality not covered by the Objective-C language. Notably, 
the Foundation Framework: 

• Makes software development easier by introducing consistent 
conventions for things such as object deallocation 

• Supports Unicode strings, object persistence, and object 
distribution 

• Provides a level of operating-system independence, 
enhancing application portability 

Root Class 

NSObject, the principal root class, provides the fundamental 
behavior and interface for objects. It includes methods for 
creating, initializing, deallocating, copying, comparing, and 
querying objects. Almost all OpenStep objects inherit ultimately 
from NSObject. 


methods for searching, combining, and comparing strings. 
NSCharacterSet represents various groupings of characters 
which are used by NSString. An NSScanner object scans 
numbers and words from an NSString object. For more 
information, see "NSString: A String for All Countries" on page 82. 

You use NSBundle objects to load code and localized resources 
dynamically (see "Only When Needed: Dynamically Loading 
Resources and Code" on page 118). The NSUserDefaults class 
enables you to store and access default values based on locale. 

Object Persistence and Distribution 

NSSerializer makes it possibleto represent the data thatan object 
contains in an architecture-dependent way. NSCoder and its 
subclasses take this process a step further by storing class 
information along with the data, thereby enabling archiving and 
distribution. Archiving (NSArchiver) stores encoded objects and 
other data in files. Distribution denotes the transmission of 
encoded object data between different processes and threads 
(NSPortCoder, NSConnection, NSDistantObject, and others). 


Deallocation of Objects 

The Foundation Framework introduces a mechanism for ensuring 
that objects are properly deallocated when they're no longer 
needed. This mechanism, which depends on general 
conformance to a policy of object ownership, automatically 
tracks objects that are marked for release within a loop and 
deallocatesthem atthe close of the loop. See "Object Ownership, 
Retention, and Disposal" on page 88 for more information. 

Data Storage and Access 

The Foundation Framework provides object-oriented storage for 

• Arrays of raw bytes (NSData) and characters (NSString) 

• Simple C data values (NSValue and NSNumber) 

• Objective-C objects of any class (NSArray, NSDictionary, 
NSSet, and NSPPL) 

NSArray, NSDictionary, and NSSet (and related mutable classes) 
are collection classesXhatalso allow you to organize and access 
objects in certain ways (see "The Collection Classes" on page 74). 

Text and Internationalization 

NSString internally represents text in various encodings, most 
importantly Unicode, making applications inherently capable of 
expressing a variety of written languages. NSString also provides 


Other Functionality 

Date and time. The NSDate, NSCalendarDate, and NSTimeZone 
classes generate objects that represent dates and times. They 
offer methods for calculating temporal differences, for displaying 
dates and times in any desired format, and for adjusting times and 
dates based on location in the world. 

Application coordination. NS Notification, NSNotificationCenter, 
and NSNotificationQueue implement a system for broadcasting 
notifications of changes within an application. Any object can 
specify and post a notification, and any other object can register 
itself as an observer of that notification. You can use an NSTlmer 
object to send a message to another object at specific intervals. 

Operating system services. Many Foundation classes help to 
insulate your code from the peculiarities of disparate operating 
systems. 

• NSFileManager provides a consistent interface for file-system 
operations such as creating files and directories, enumerating 
directory contents, and moving, copying, and deleting files. 

• NSThread and NSProcessInfo let you create multi-threaded 
applications and query the environment in which an 
application runs. 

• NSUserDefaults allows applications to query, update, and 
manipulate a user's default settings across several domains: 
globally, per application, and per language. 
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Before You Go On - 

If you don't want to allow an instance variable's value to be changed by anyone outside of your 
class, provide a set method for the instance variable. If you do provide a set method, make 
sure objects of your own class use it when specifying a value for the instance variables. This has 
important implications for subclasses of your class. 

Exercise: The previous example shows the declarations for only a few accessor 
methods. Every instance variable of the Country class should have an accessor 
method that returns a value and one that sets a value. Complete the remaining 
declarations. 


Now that you’ve declared the Country class’s accessor methods, implement 
them. 


3 Implement the accessor 
methods. 

Select Country.m in the project 
browser. 

Write the code that obtains and 
sets the values of instance 
variables. 


- (NSString *)name /* 1 */ 

{ 

return name; 

} 

- (void)setName:(NSString *)str /* 2 */ 

{ 

[name autorelease]; 
name = [str copy]; 

} 

/* more accessor method implementations follow */ 


1. For “get” accessor methods (at least when the instance variables, like Travel 
Advisor’s, hold immutable objects) simply return the instance variable. 


In many situations you can send 
retain instead of copy to keep an 
object around. But for “value” 
type objects, such as Country’s 
instance variables, copy is better. 
For the reason why, and for more 
on autorelease, retain, copy, and 
related messages for object 
disposal and object retention, see 
“Object Ownership, Retention, 
and Disposal” on page 88. 


2. For accessor methods that set object values, first send autorelease to the current 
instance variable, then copy (or retain) the passed-in value to the variable. The 
autorelease message causes the previously assigned object to be released at the 
end of the current event loop, keeping current references to the object valid 
until then. 

If the instance variable has a non-object value (such as an integer or float 
value), you don’t need to autorelease and copy; just assign the new value. 

Before You Go On - 

Exercise: The example above shows the implementation of the accessor methods 
for the name instance variable. Implement the remaining accessor methods. 
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4 Write the object-initialization 
and object-deallocation code. 

Implement the init method, as 
shown here. 

Implement the dealloc method, 
following the suggestions in the 
Required Exercise, below. 


Don’t substitute nil when empty 
objects are expected, and vice 
versa.The Objective-C keyword 
nil represents an “object” with an 
id (value) of zero. An empty 
object (such as @“”) is a true 
object; it just has no content of its 
given type. To learn more about 
Objective-C keywords, see 
Object-Oriented Programming and 
the Objective-C Language. 


Note that release itself doesn’t 
deallocate objects, but it leads to 
their deallocation. For more on 
release and autorelease, see 
“Object Ownership, Retention, 
and Disposal” on page 88. 


- (id)init 
{ 

[super init]; /* 1 */ 

name = @""; /* 2 * / 

airports = {a"” ; 
airlines = 

transportation = "; 

hotels = 
languages = @""; 
currencyName = @"; 
comments = ; 

return self; /* 3 */ 

} 

1. Invokes super’s (the superclass’s) init method to have inherited instance 
variables initialized. Always do this first in an init method. 

2. Initializes an NSString instance variable to an empty string. is a compiler- 
supported construction that creates an immutable NSString object from the 
text enclosed by the quotes. You could have just as well typed: 

name = Howdy Doody"; 

But that wouldn’t have been practical as an initial value. You don’t need to 
initialize instance variables to null values because the run-time system does 
it for you; it assigns nil to objects, zeroes to integers and floats, and NULL to 
char *’s if they’re not explicitly initialized. However, you should initialize 
instance variables that take other starting values. 

3. By returning self you’re returning a true instance of your object; up until this 
point, the instance is considered undefined. 

Before You Go On - 

Implement the dealloc method. In this method you release (that is, send release 
or autorelease to) objects that you’ve created, copied, or retained (which don’t 
have an impending autorelease). For the Country class, release all objects held as 
instance variables. If you had other retained objects, you would release them, 
and if you had dynamically allocated data, you would free it. When this method 
completes, the Country object is deallocated. The dealloc method should send 
dealloc to super as the last thing it does, so that the Country object isn’t released 
by its superclass before it’s had the chance to release all objects it owns. 
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5 Implement the methods that 
archive and unarchive the object. 

Implement the 

encodeWithCoder: method, as 
shown at right. 


Implement the initWithCoder: 
method, as shown at right. 


The NSCoder class provides a 
number of methods for encoding 
and decoding objects and data of 
standard C types. See the 
specification of the NSCoder 
class in the Foundation 
framework reference 
documentation. 


You want the Country objects created by the Travel Advisor application to be 
persistent. That is, you want them to “remember” their state between sessions. 
Archiving lets you do this by encoding the state of application objects in a file 
along with their class membership. The NSCoding protocol defines two 
methods that enable archiving for a class: encodeWithCoder: and initWithCoder:. 


- (void)encodeWithCoder:(NSCoder *)coder 

{ 

[coder 
[coder 
[coder 
[coder 
[coder 
[coder 
[coder 
[coder 
[coder 
[coder 

} 

1. The encodeObject: method encodes a single object in the archival file. 

2. For both object and non-object types, you can use encodeValueOfObjCType:at:. 

- (id)initWithCoder:(NSCoder *)coder 

{ 

name = [[coder decodeObject] copy]; /* 1 */ 

airports = [[coder decodeObject] copy]; 

airlines = [[coder decodeObject] copy]; 

transportation = [[coder decodeObject] copy]; 

hotels = [[coder decodeObject] copy]; 

languages = [[coder decodeObject] copy]; 

[coder decodeValueOfObjCType:"s" at:&englishSpoken]; 
currencyName = [[coder decodeObject] copy]; 

[coder decodeValueOfObjCType:"f" at:&currencyRate]; 
comments = [[coder decodeObject] copy]; 

return self; - /* 2 */ 

} 

1. The order of decoding should be the same as the order of encoding; since 
name is encoded first it should be decoded first. Use copy when you assign 
value-type objects to instance variables (see “Object Ownership, Retention, 
and Disposal” on page 88 ). NSCoder defines decode... methods that 
correspond the encode... methods, which you should use. 

2. As in any init... method, end by returning self —an initialized instance. 


encodeObject:name]; /* 1 */ 

encodeObject:airports]; 

encodeObject:airlines]; 

encodeObject:transportation]; 

encodeObject:hotels] ; 

encodeObject:languages]; 

encodeValueOfObjCType:"s" at:&englishSpoken]; /* 2 */ 
encodeObj ect:currencyName]; 

encodeValueOfObj CType:"f" at:&currencyRate]; 
encodeObj ect:comments]? 
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Object Ownership, Retention, and Disposal 



The problem of object ownership and disposal is a natural 
concern in object-oriented programming. When an object is 
created and passed around various "consumer 1 objects in an 
application, which object is responsible for disposing of it? And 
when? If the object is not deallocated, memory leaks. If the object 
is deallocated too soon, problems may occur in other objects that 
assume its existence, and the application may crash. 

The Foundation Framework introduces a mechanism and a policy 
that helps to ensure that objects are deallocated when—and only 
when—they are no longer needed. 

Who Owns Which Object? 

The policy is quite simple: You are responsible for disposing of all 
objects that you own. You own objects that you create, either by 


allocating or copying them. You also own (or share ownership in) 
objects that you retain, since retain increments an object's 
reference count (see facing page). The flip side of this rule is: If 
you don't own an object, you need not worry about releasing it. 

OK, but now another question arises. If the owner of an object 
must release the object within its programmatic scope, how can 
it give that object to other objects? The short answer is: the 
autorelease method, which marks the receiver for later release, 
enabling it to live beyond the scope of the owning object so that 
other objects can use it. 

The autorelease method must be understood in a larger context 
of the autorelease mechanism for object deallocation. Through 
this programmatic mechanism,you implement the policy of object 
ownership and disposal. 


How Autorelease 
Pools Work: 

An Example 


myObj 


yourObj 



Autorelease 

pool 


retention count 


A. myObj creates an object: 

anObj = [[MyClass alloc] init]; 

B. myObj returns the object to yourObj, autoreleased: 

return [anObj autorelease]; 

The object is "put" in the autorelease pool; that is, the autorelease 
pool starts tracking the object. 

C. yourObj retains the object: 

[anObj retain]; 

If the object wasn't retained it would be deallocated atthe end of the 
current event cycle. 

D. Atthe end of the event cycle, the autorelease pool sends release to 
all of its objects, thereby decrementing their reference counts. Now 
with a reference count of 1 , anObj stays in the autorelease pool. 

E. yourObj sends autorelease to the object Atthe end of the event 
cycle, the autorelease pool sends release to its objects; since 
anObj's reference count is now zero, it's deallocated. 

For a fuller description of object ownership and disposal, see the 
introduction to the Foundation Framework reference documentation. 



yourObj 



Autorelease pool 



yourObj 



Autorelease pool 


-- — 4 - 1 : 


yourObj 



Autorelease pool 
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Reference Counts, Autorelease Pools, and Deallocation 

Each object in the Foundation Framework has an associated 
reference count. When you allocate or copy an object, its 
reference count is set at 1. You send release to an object to 
decrement its reference count. When the reference count 
reaches zero, NSObject invokes the object's dealloc method, and 
the object is destroyed. However, successive consumers of the 
object can delay its destruction by sending it retain, which 
increments the reference count You retain objects to ensure that 
they won't be deallocated until you're done with them. 

Each application has an autorelease pool. An autorelease pool 
tracks objects marked for eventual release and releases them at 
the appropriate time. You put an object in the pool by sending the 
object an autorelease message. When your code finishes 
executing and control returns to the application object (typically 
at the end of the event cycle), the application object sends 
release to the autorelease pool, and the pool releases each 
object it contains. If afterwards the reference count of an object 
in the pool is zero, the object is deallocated. 

Putting the Policy Into Practice 

When an object is used solely within the scope of the method that 
creates it, you can deallocate it immediately by sending it release. 
Otherwise, send autorelease to all created objects that you no 
longer need but will return or pass to other objects. 

You shouldn't release objects that you receive from other objects 
(unless you precede the release or autorelease with a retain). You 
don't own these objects, and can assume that their owner has 
seen to their eventual deallocation. You can also assume that 
(with some exceptions, described below) a received object 
remains valid within the method it was received in. That method 
can also safely return the object to its invoker. 

You should send release or autorelease to an object only as many 
times as are allowed by its creation (one) plus the number of 
retain messages you have sent it. You should never send free to a 
OpenStep object. 


Implications of Retained Objects 

When you retain an object you're sharing it with its owner and 
other objects that have retained it. While this might be what you 
want, it can leadto some undesirable consequences. Ifthe owner 
is released, any objectyou received from it and retained is usually 
invalid. If you had retained an instance variable of the owning 
object, and that instance variable is reassigned, your reference 
would also become invalid. 

copy Versus retain 

When deciding whether to retain or copy objects, it helps to 
categorize them as value objects or entity objects. Value objects 
are objects such as NSNumbers or NSStrings that encapsulate a 
discrete, limited set of data. Entity objects, such as NSViews and 
NSWindows,tend to be larger objects that manage and 
coordinate subordinate objects. For value objects, use copy when 
you wantyour own "snapshot" of the object; use retain when you 
intend to share it. Always retain entity objects. 

In accessor methodsthatset value-object instance variables,you 
usually (but not always) want to make your own copy of the object 
and not share it. (Otherwise it might change without your 
knowing.) Send autorelease to the old object and then send 
copy —not retain —to the new one: 

- (void)setTitle:(NSString *)newTitle 
{ 

[title autorelease]; 
title = [newTitle copy]; 

} 

OpenStep framework classes can, for reasons of efficiency, 
return objects cast as immutable when to the owner (the 
framework class) they are mutable. Thus there is no guarantee 
that a vended framework object won't change, even if it is of an 
immutable type. The precaution you should take is evident: copy 
objects obtained from framework classes if it's important the 
object shouldn't change from under you. 
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Implementing the TAController Class 

The TAController class plays a central role in the Travel Advisor application. As 
the application’s controller object, it transfers data from the model objects 
(Country instances) to the fields of the interface and, when users enter or modify 
data, back to the correct Country object. The TAController must also coordinate 
the data displayed in the table view with the current object, and it must do the 
right thing when users select an item in the table view or click the Add or Delete 
button. All custom code specific to the user interface resides in TAController. 

The mechanics of this activity require an array (NSMutableArray) and a 
dictionary (NSMutableDictionary) for storing and accessing Country data. The 
following diagram illustrates the relationship among interface components, 
TAController, and the sources of data. 



The dictionary contains Country objects (values) that are identified by the 
names of countries (keys). The dictionary is the source of data for the fields of 
Travel Advisor. The array derives from the dictionary and is sorted. It is the 
source of data for the table view. 

After describing what other instance variables you must add to TAController, 
this section covers the following implementation tasks: 

• Getting the data from Country objects to the interface and back 

• Getting the table view to work, including updating Country records 

• Adding and deleting “records” (Country objects) 

• Formatting and validating field values 

• “Housekeeping” tasks (application management) 
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1 UpdateTAController.fi. 

Import Country.h. 

Add the instance-variable 
declarations shown at right 

The variables countryDict and countryKeys identify the array and the dictionary 
discussed on the previous page. The boolean recordNeedsSaving flags that record 
if the user modifies the information in any field. 


NSMutableDictionary *countryDict; 
NSMutableArray *countryKeys; 

BOOL recordNeedsSaving; 


Add the enum declaration shown 

at right between the last #import enum LogisticsFormTags { 

directive and the ©interface LGairports=0, 

directive. LGairlines, 

LGtransportation, 
LGhotels 

}; 


This declaration is not essential, but the enum constants provide a clear and 
convenient way to identify the cells in the Logistics form. Methods such as 
cellAtlndex: identify the editable cells in a form through zero-based indexing. 
This declaration gives each cell in the Logistics form a meaningful designation. 


Turbo Coding With Project Builder 

When you write code with Project Builder you have a set of 
"workbench" tools at your disposal, among them: 

Indentation 

In Preferences you can set the characters at which indentation 
automatically occurs, the number of spaces per indentation, and 
other global indentation characteristics. The Edit menu includes 
the Indentation submenu, which allows you to indent lines or 
blocks of code on a case-by-case basis. 

Brace and Bracket Checking 

Double-click a brace (left or right, it doesn't matter) to locate the 
matching brace;the code in-between the braces is highlighted. In 
an identical fashion, double-click a square bracket in a message 
expression to locate the matching bracket. 

Name completion 

Name completion is a facility that, given a partial name, 
completes it from all symbols known by the project. You activate it 


by pressing Escape (or Tab, if that key is bound in Preferences). 
You can use name completion in the code editor and in all panels 
where you are finding information or searching for files to open. 

As an example: you know there’s a certain constant to use with 
fonts, but you cannot remember it. In your code, type NSFont. 
Then press the Escape key several times. These symbols appear 
in succession (the found portion is underlined): 

NSFontldentityMatrix 

NSFontManager 

NSFontPanel 


You can issue the most common Emacs commands in Project 
Builder's code editor. (Emacs is a popular editor for writing code.) 
For example, there are the commands page-forward (Control-v), 
word-forward (Meta-f), delete-word (Meta-d), kill-forward 
(Control-k), and yank from kill ring (Control-y). You can also 
perform an incremental search by pressing Control-s; this 
command displays a small search panel and takes you to the next 
occurrence of whatever you type. 


Emacs Bindings 
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Data Mediation 

TAController acts as the mediator of data exchanged between a source of data 
and the display of that data. Data mediation involves taking data from fields, 
storing it somewhere, and putting it back into the fields later. TAController has 
two methods related to data mediation: populateFields: puts Country instance data 
into the fields of Travel Advisor and extractFields: updates a Country object with 
the information in the fields. 


2 Implement the methods that 
transfer data to and from the 
application's fields. 

Implement the populateFields: 
method as shown at right. 


- (void)populateFields:(Country *)aRec 

{ 

[countryField setStringValue:[aRec name]]; /* 1 */ 

[[logisticsForm cellAtIndex:LGairports] setStringValue: 

[aRec airports]]; /* 2 */ 

[[logisticsForm cellAtIndex:LGairlines] setStringValue: 

[aRec airlines]]; 

[[logisticsForm cellAtIndex:LGtransportation] setStringValue: 
[aRec transportation]]; 

[[logisticsForm cellAtIndex:LGhotels] setStringValue: 

[aRec hotels]]; 

[currencyNameField setStringValue:[aRec currencyName]]; 
[currencyRateField setFloatValue:[aRec currencyRate]]; 

[languagesField setStringValue:[aRec languages]]; 
[englishSpokenSwitch setState:[aRec englishSpoken]]; 

[commentsField setstring:[aRec comments]]; 

: g i 7 ; ; ; ; r 

[countryField selectText:self]; /*. 3 */ 

} 


1. Causes the Country field to display the value of the name instance variable of 
the Country record (aRec) passed into the method. Since [aRec name] is nested, 
the object it returns is used as the argument of setStringValue:, which sets the 
textual content of the receiver (in this case, an NSTextFieldCell). 

2. The cellAtlndex: message is sent to the form and returns the cell identified by 
the enum constant LGairports. 

3. Selects the text in the Country field or, if there is no text, inserts the cursor. 

Although it doesn’t do anything with data, the blankFields: method is similar in 
structure to populateFields:. The blankFields: method clears whatever appears in 
Travel Advisor’s fields by inserting empty string objects and zeros. 
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Implement the blankFields: 
method as shown at right. 


- (void)blankFields:(id)sender 

{ 

[countryField setStringValue:"]; 

[[logisticsForm cellAtlndex:LGairports] setStringValue:@; 

[[logisticsForm cellAtlndex:LGairlines] setStringValue:"3; 

[[logisticsForm cellAtlndex:LGtransportation] setStringValue: 
[[logisticsForm cellAtlndex:LGhotels] setStringValue:"]; 

[currencyNameField setStringValue:@""]; 

[currencyRateField setFloatValue:0.000]; 

[languagesField setStringValue:@""]; 

[englishSpokenSwitch setState:NO]; /* 1 */ 

[currencyDollarsField setFloatValue:0.00]; 

[currencyLocalField setFloatValue:0.00]; 

[celsius setlntValue:0]; 

[commentsField setstring:" ]; /* 2 */ 

[countryField selectText:self]; 

} 

1. The setState: message affects the appearance of two-state toggled controls, 
such as a switch button. With an argument of YES, the checkmark appears; 
with an argument of NO, the checkmark is removed. 

2. The setString: message sets the textual contents of NSText objects (such as the 
one enclosed by the scroll view). 

Before You Go On - 

Exercise: Implement the extractFields: method. In this method set the values of the 
passed-in Country record’s instance variables with the contents of the associated 
fields. 

Tip: Use the stringValue method to get field contents and use Country’s accessor 
methods to set the values of instance variables. 
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Finding Information Within Your Project 


il 


:i||lji!itisii II 


The Project Find Panel 

The Project Find panel lets you find any symbol defined or referenced in your project. It 
also allows you to look up related reference documentation, search for text project¬ 
wide using regular expressions, and replace symbols or strings of text. To use the full 
power of Project Find, your project must be indexed; once it is, you have access to all 
symbols that the project references, including symbols defined in the frameworks and 
libraries linked into the project. 


Lists the targets of recent 
find operations; selecting one 
re-displays the results in the 
browser. 


Click a book icon to see ther 
related reference 
documentation. 


TravelAdvisor — Project Find 
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Search for: symbol definition ; 
symbol reference, textual 
strings (with or without 
regular expressions) 


• Find and replace buttons. 


• Search results. 

Click an item to display 
the relevant code 


Symbol Definition Search Syntax 

You can narrow your search for definitions of symbols by 
indicating type in the Find field of the Project Find panel along with 
the symbol name. Once the symbol items are listed in the browser, 
you can click an item to navigate to the definition in the header 
file, or click a book icon to display the relevant reference 
documentation. 

The following table lists examples of searching for symbol 
definitions by type; 


Example 


Finds Definition For 


@NSArray 

<NSCoding> 

-objectAtlndex: 

+stringWithFormat: 

[NSBox controlView] 

NSRunAlertPanelO 

NSApp 

I if® 


NSArray class 
NSCoding protocol 


Instance method 
Class method 




Method specific to class 

Function 

Type or constant 


M. 


Other Ways of Finding Information 

Project Builder includes other facilities for finding information: 

• Incremental search:Control-s brings up the incremental- 
search panel for the currently edited file. As you type, the 
cursor advances to the next sequence of characters in the file 
that match what you type. Click Next (or press Control-s) to go 
to the next occurrence; click Prev (or press Control-r) to go to 
the previous occurrence. 

• Man pages: Choose Edit ► Find ► Man Page to bring up the 
"Show man page" panel. Enterthe name of a tool in the panel 
to get the man page on that tool. 

• Librarian via Services: Select a symbol or any word (for 
example, "fonts") in Project Builder, then choose Services ► 
Librarian ► Search to have Digital Librarian find related 
documentation. 




Help: Project Builder and Interface Builder also feature 
context-sensitive help and task-related help. See "Where to 
Go For Help" in chapter 2, "Currency Converter Tutorial" for 
details. 


1 


. 
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Getting the Table View to Work 

Table views are objects that display data as records (rows) with attributes 
(columns). The table view in Travel Advisor displays the simplest kind of 
record, with each record having only one attribute: a country name. 

Table views get the data they display from a data source. A data source is an 
object that implements the informal NSTableDataSource protocol to respond to 
NSTableView requests for data. Since the NSTableView organizes records by 
zero-based indexing, it is essential that the data source organizes the data it 
provides to the NSTableView similarly: in an array. 


3 Implement the behavior of the 
table view's data source. 

In TAController's awakeFromNib 
method, create and sort the array 
of country names. 

In the same method, designate 
self as the data source. 


If users are supposed to edit the 
cells of the table view, you would 
also make TAController the 
delegate of the table view at this 
point (with setDelegate:).The 
delegate receives messages 
relating to the editing and 
validation of cell contents. For 
details, see the specification on 
NSTableView in the Application 
Kit reference documentation. 


- (void) awakeFromNib 
{ 

NSArray *tmpArray = [[countryDict allKeys] /* 1 */ 

sortedArrayUsingSelector:©selector(compare:)]; 
countryKeys = [[NSMutableArray alloc] initWithArray:tmpArray]; 

[tableView setDataSource:self3; /* 2 */ 

[[[tableView tableColumns] objectAtIndex:0] /* 3 */ 

setldentifier:Countries”]; 

[tableView sizeLastColumnToFit]; 

} 

1. The [countryDict allKeys] message returns an array of keys (country names) from 
the unarchived dictionary that contains Country objects as values. The 
sortedArrayUsingSelector: message sorts the items in this “raw” array using the 
compare: method defined by the class of the objects in the array, in this case 
NSString (this is an example of polymorphism and dynamic binding). The 
sorted names go into a temporary NSArray—since that is the type of the 
returned value—and this temporary array is used to create a mutable array, 
which is then assigned to countryKeys. A mutable array is necessary because 
users may add or delete countries from the application. 

2. The [tableView setDataSource:self] message identifies the TAController object as 
the table view’s data source. The table view will commence sending 
NSTableDataSource messages to TAController. (You can effect the same 
thing by setting the NSTableView’s dataSource outlet in Interface Builder.) 

3. Every column has an identifier to associate it with a column, which is itself 
usually associated with an attribute. By default, the identifier is a number: the 
first column is 0, the second column is 1, and so on. This compound message 
makes the identifier a string object and thus binds it semantically to the 
attribute. The tableColumns method returns all NSTableColumns in a array; in 
this case, only the single column of this table view. The setldentifier: message 
sets the value. 
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To fulfill its role as data source, TAController must implement two methods of 
the NSTableDataSource informal protocol. 


Implement two methods of the 
NSTableDataSource informal 
protocol: 

- numberOfRowslnTableView: 
-tableView: 

objectValueForTableColumn: 

row: 


- (int) numberOf RowsInTableView: (NSTableView *) theTableView 

{ /* 1 */ 
return [countryKeys count]; 

} 

- (id)tableView:(NSTableView *)theTableView /* 2 */ 

objectValueForTableColumn:(NSTableColumn *)theColumn 
row:(int)rowlndex 

{ 

if ([[theColumn identifier] isEqualToString:©"Countries"]) 
return [countryKeys objectAtIndex:rowlndex]; 

else 

return nil; 

} 


1. Returns the number of country names in the countryKeys array. 

If you had an application with multiple table views, each would invoke this 
NSTableView delegation method (as well as the others). By evaluating the 
theTableView argument, you could distinguish which table view was involved. 

2. This method first evaluates the column identifier to determine if it’s the right 
column (it should always return “Countries”). If it is, the method returns the 
country name from the countryKeys array that is associated with rowlndex. This 
name is then displayed at rowlndex of the column. (Remember, the array and 
the cells of the column are synchronized in terms of their indexing.) 

The NSTableDataSource informal protocol has a another method, 
tableView:setObjectValue:forTableColumn:row^ that you won’t implement in this 
tutorial. This method allows the data source to extract data entered by users into 
table-view cells; since Travel Advisor’s table view is read-only, there is no need 
to implement it. 
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Getting in on the Action: Delegation and Notification 


A lot goes on in a running application: events are being 
interpreted, files are being read, views are being drawn. Because 
your custom objects might be interested in any of these activities, 
OpenStep offer two mechanisms through which your objects can 
participate or be kept informed of events going on in the 
application: delegation and notification. 


Notification 

A notification is a message that is broadcast to all objects in an 
application that are interested in the event the notification 
represents. As does the informational delegation message, the 
notification informs these observers that this event took place. It 
can also pass along relevant data about the event. 


Delegation 

Many OpenStep framework objects hold a delegate as an 
instance variable. A delegate is a object that receives messages 
from the framework object when specific events occur. 
Delegation messages are of several types, depending on the 
expected role of the delegate: 

• Some messages are purely informational, occurring after an 
event has happened. They allow a delegate to coordinate its 
actions with the other object. 

• Some messages are sent before an action will occur, allowing 
the delegate to veto or permit the action. 

• Other delegation messages assign a specific task to a 
delegate, like filling a browser with cells. 



Here's the way the notification process works: 



You can set your custom objectto be the delegate of a framework 
object programmatically or in Interface Builder. Your custom 
classes can also define their own delegate variables and 
delegation protocols for client objects. 


• Objects who are interested in an event that happens 
elsewhere in the application — say the addition of a record to 
a database — register themselves with a notification center 
(an instance of NSNotificationCenter) as observers of that 
event Delegates of an object that posts notifications are 
automatically registered as observers of those notifications. 

• The object that adds the objectto the database (or some such 
event) posts a notification (an instance of NSNotification) to a 
notification center. The notification contains a tag identifying 
the notification, the id of the associated object, and, optionally, 
a dictionary of supplemental data. 

• The notification center then sends a message to each 
observer, invoking the method specified by each, and passing 
in the notification. 

Notifications hold some advantages over delegation messages as 
a means of inter-application communication.They allowan object 
to synchronize its behavior and state with multiple objects in an 
application, and without having to know the identity of those 
objects. With notification queues , it is also possible to post 
notifications asynchronously and coalesce similar notifications. 
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The final thing you need to do to get the table view working is to respond to 
mouse clicks in it. As you recall, you defined in Interface Builder the 
handleTVCIick: action for this purpose. This method must do a number of things: 

• Save the current Country object or create a new one. 

• If there’s a new record, re-sort the array providing data to the table view. 

• Display the selected record. 

- (void)handleTVCIick:(id)sender 

{ 

Country *aRec, *newRec / *newerRec; 
int index; 

/* does current obj need to be saved? */ 

if (recordNeedsSaving) { /* 1 */ 

/* is current object already in dictionary? */ 

if (aRec=[countryDict objectForKey:[countryField stringValue]]) 

{ 

/* remove if it's been changed */ 
if (aRec) { 

NSString *country = [aRec name]; 

[countryDict removeObjectForKey:country]; 

[countryKeys removeObj ect:country]; 

} 

} 

/* Create Country obj, add to diet, add name to keys array */ 
newRec = [[Country alloc] init]; 

[self extractFields:newRec]; 

[countryDict setObject: newRec forKey: [countryFieldstringValue] ] ; 
[countryKeys addObject:[countryField stringValue]]; 

/* sort array here */ 

[countryKeys sortUsingSelector:©selector(compare:)]; 

[tableView tile]; 

I'. . ' . . • ' . - ' i' ' '■ , ' • - ? i 

} 

index = [sender selectedRow]; 

if (index >= 0 && index < [countryKeys count]) { /* 2 */ 

newerRec = [countryDict objectForKey: 

[countryKeys objectAtlndex:index]]; 

[self populateFields:newerRec]; 

[commentsLabel setStringValue:[NSString stringWithFormat: 

©"Notes and Itinerary for %@", [countryField stringValue]]]; 
recordNeeds Saving=NO; 

} 

} 

This method has two major sections, each introduced by an if statement. 


4 Update records. 

Implement the method that 
respondstouserselectionsinthe 
table view. 
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1. When any Country-object data is added or altered, Travel Advisor sets the 
recordNeedsSaving flag to YES (you’ll learn how to do this on later on). If 
recordNeedsSaving is YES, first delete any existing Country record for that 
country from the dictionary and also remove the country name from the table 
view’s array. (Upon removal, the objects are automatically released by the 
array.) Then create a new Country instance and initialize it with the values 
currently on the screen; add the instance to the dictionary, add the country 
name to the table view’s array, sort the array, and reset the recordNeedsSaving 
flag. At the end, invoke the tile method , which (among other things) causes 
the table view to request data from its data source. 

2. The selectedRow message queries the table view for the row index of the cell 
that was clicked. If this index is within expected bounds, use it to get the 
country name from the array, and then use the country name as the key to get 
the associated Country instance. Write the instance-variable values of this 
instance to the fields of the application, update the “Notes and Itinerary for” 
label. 

Optional Exercise - 

Application developers often like to have key alternatives to mouse actions such 
as clicking a table view. One way of acquiring a key alternative is to add a menu 
cell in Interface Builder, specify a key as an attribute of the cell, define an action 
method that will be invoked, and then implement that method. 

The methods nextRecord: and prevRecord: should be invoked when users chose 
Next Record and Prev Record or type the key equivalents Command-n and 
Command-r. In TAControlIer.m, implement these methods, keeping the following 
hints in mind: 

1. Get the index of the selected row (selectedRow). 

2. Increment or decrement this index, according to which key is pressed (or 
which command is clicked). 

3. If the start or end of the table view is encountered, “wrap” the selection. 
(Hint: Use the index of the last object in the countryKeys array.) 

4. Using the index, select the new row, but don’t extend the selection. 

5. Simulate a mouse click on the new row by sending handleTVCIick: to self. 
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Adding and Deleting Records 

When users click Add Record to enter a Country “record,” the addRecord: 
method is invoked. You want this method to do a few things besides adding a 
Country object to the application’s dictionary: 


• Ensure that a country name has been entered. 

• Make the table view reflect the new record. 

• If the record already exists, update it (but only if it’s been modified). 


5 Implement the method that adds 
a Country object to the 
NSDictionary "database." 


- (void)addRecord:(id)sender 

{ 

Country *aCountry; 

NSString *countryName = [countryField stringValue]; 

/* 1 */ 

if (countryName && (![countryName isEqualToString:@""])) { 
aCountry = [countryDict objectForKey:countryName]; 
if (aCountry && recordNeedsSaving) { 

/* remove old Country object from dictionary */ 

[countryDict removeObj ectForKey:countryName 3; 
[countryKeys removeObject:countryName]; 
aCountry = nil? 

} 

if (!aCountry) /* record is new or has been removed */ 
aCountry = [[Country alloc] init]; 
else /* record already exists and hasn't changed */ 
return; 


/* 2 


/* 3 



[self extractFields:aCountry]; 

[countryDict setObject:aCountry forKey:[aCountry name]]; 
[countryKeys addObject:[aCountry name]]? 

• [countryKeys sortUsingSelector:©selector(compare:)]; 


recordNeedsSaving=NO;. 

[commentsLabel setStringValue:[NSString stringWithFormat: 

©"Notes and Itinerary for %@",[countryField stringValue] 
[countryField selectText:self]; 


/* 4 */ 




[tableView tile]; 

[tableView selectRow:[countryKeys indexOfObject: 
[aCountry name]]. byExtendingSelection:NO]; 


} 


: I®; 



1. This section of code verifies that a country name has been entered and sees 
if there is a Country object in the dictionary. If there’s no object for the key, 
objectForKey: returns nil. If the object exists and it’s flagged as modified, the 
code removes it from the dictionary and removes the country name from the 
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countryKeys array. Note that removing an object from a dictionary or array also 
releases it, so the code sets aCountry to nil. It then tests aCountry and, if it’s nil, 
creates a new object; otherwise it just returns, because an object already exists 
for this country and it hasn’t been modified. 

2. After updating the new Country object with the information on the 
application’s fields (extractFields:), this code adds the Country object to the 
dictionary and the country name to the countryKeys array. 

3. This section of code performs some things that have to be done, such as 
resetting the recordNeedsSaving flag and updating the label over the scroll view 
to reflect the just-added country. 

4. The tile message forces the table view to update its contents. The 
selectRow.byExtendingSelection: message highlights the new record in the table 
view. 

Before You Go On - -- 

Exercise: Implement the deleteRecord: method. Although similar in structure to 
addRecord: this method is much simpler, because you don’t need to worry about 
whether a Country record has been modified. Once you’ve deleted the record, 
remember to update the table view and clear the fields of the application. 


Abstract Classes and Class Clusters 

Many of the classes in the Foundation 
Framework fall into functional constellations 
of public and private classes called class 
clusters . Class clusters simplify the 
programming interface and permit more 
efficient storage of data. 

An abstract class (such as NSArray) defines 
the public interface for objects vended from 
class clusters. Abstract classes declare 
methods common to private/concrete 
subclasses, but do not declare any instance 
variables to hold data—that's done by the 
private classes. When you send an object- 
creation message to an abstract class, it 
instantiates and returns an instance of the 


appropriate private subclass. What's 
appropriate depends on the creation 
method, which indicates the type of storage 
required. The class membership of the 
returned object is hidden, but its interface, as 
declared by the abstract superclass, is 
public. 

Many OpenStep class clusters have two or 
more abstract classes. Usually one class 
provides the interface for obtaining 
immutable objects (for example, NSArray) 
and another class, which inherits from the 
mutable class, vends mutable versions of the 
same type of object (NSMutableArray). 
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Field Formatting and Validation 

Travel Advisor has several numeric fields. Some display temperatures while 
others display currency amounts. In this stage, you’ll enable these fields to 
format their contents by using a formatting API defined in the Application Kit. 


6 Format and validate numeric 
fields. 

Set the entry type and floating¬ 
point format of some TAController 
fields in the awakeFromNib 
method. 


- (void) awakeFromNib 

{ 

[[currencyRateField cell] setEntryType:NSFloatType]; 

[[currencyRateField cell] setFloatingPointFormat:YES 
left:2' right:1]; 

[ [currencyDollarsField cell] setEntryType-.NSFloatType] ; 

[[currencyDollarsField cell] setFloatingPointFormat:YES left:5 
right:2]; 

[[currencyLocalField cell] setEntryType:NSFloatType]; 

[[currencyLocalField cell] setFloatingPointFormat:YES left:5 
right:2]; 

[[celsius cell] setEntryType:NSFloatType]; 

[[celsius cell] setFloatingPointFormat:YES left:2 right:!]; 


The NSCell class provides methods for specifying how cell values are 
formatted. In this instance, setEntryType: sets the type of value as a float and 
setFloatingPointFormat:left:right: specifies the number of digits on each side of the 
decimal point. 

The NSControfclass gives you an API for validating the contents of cells. 
Validation verifies that the values of cells fall within certain limits or meet 
certain criteria. In Travel Advisor, we want to make sure that the user does not 
enter a negative value in the Rate field. 

The request for validation is a message —controhisValidObject: —that a control 
sends to its delegate. The control, in this case, is the Rate field. 


In awakeFromNib, make 
TAController a delegate of the 
field to be validated. 

Implement the 

controhisValidObject: method to 
validate the value of the field. 


[currencyRateField setDelegate:self]; 


(BOOL)control:(NSControl *)control isValidObject:(id)obj 


if (control == currencyRateField) { /* 1 */ 

if ([obj floatValue] < 0.0) { 

NSRunAlertPanel(©"Travel Advisor", /* 2 */ 

@"Rate cannot be negative.", nil, nil, nil); 
return NO; 

} 

} 

return YES; 
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Behind "Click Here' 


Controls, Cells, and Formatters 


Controls and cells lie behind the appearance and behavior of 
most user-interface objects in OpenStep, including buttons, text 
fields, sliders, and browsers. Although they are quite different 
types of objects—controls inherit from NSControl while cells 
inherit from NSCell—they interact closely. 

Controls enable users to signal their intentions to an application, 
and thus to confro/what is happening. By interpreting mouse and 
keyboard events and asking another object to respond to them, 
controls implement the target/action paradigm described in 
"Paths for Object Communication: Outlets, Targets, and Actions" 
on page 38. Controls themselves can hold targets and actions as 
instance variables, but usually they getthis data fromthe affected 
cell (which must inherit from NSActionCell). 

Cells are rectangular areas "embedded" within a control. A 
control can hold multiple cells as a way to partition its surface into 
active areas. Cells can draw their own contents either as text or 
image (and sometimes as both), and they can respond individually 
to user actions. Since cells are typically more frugal consumers of 
memory than controls, they help applications be more efficient. 
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Controls act as managers of their cells, telling them when and 
where to draw, and notifying them when a user event (mouse 
clicks, keystrokes) occurs in their areas. This division of labor, 
given the relative "weight" of cells and controls, provides a great 
boost to application performance. 




A control does not have to have a cell associated with it, but most 
user-interface objects available on Interface Builder's standard 
palettes are cell-control combinations. Even a simple button— 
from Interface Builder or programmatically created—is a control 
(an NSButton instance) associated with an NSButtonCell. The 
cells in a control such as a matrix must be the same size, but they 
can be of different classes. More complex controls, such as table 
views and browsers, can incorporate various types of cells. 


Cells and Formatters 

When one thinks of the contents of cells, it's natural to consider 
onlytext(NSString) and images (NSImage). The content seems to 
be whatever is displayed. However, cells can hold other kinds of 
objects, such as dates (NSDate), numbers (NSNumber), and 
custom objects (say, phone-number objects). 

Formatter objects handle the textual representation of the objects 
associated with cells and translate what is typed into a cell into 
the underlying object. Using NSCell's setFormatter:, you must 
programmatically associate a formatter with a cell to getthis 
behavior. 



...and vice 
versa 


The Foundation Framework provides the NSDate For matter class 
to generate date formatters and will release other specialized 
formatter classes in the future. You can make a custom subclass 
of NSFormatter to derive your own formatters. 
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For more information on 
NSRunAlertPanell), see the 

“Functions” section of the 
Application Kit (framework) 
reference documentation. 


1. Because you might have more than one field’s value to validate, this example 
first determines which field is sending the message. It then checks the field’s 
value (passed in as the second object); if it is negative, it displays an attention 
panel and returns NO, blocking the entry of the value. Otherwise, it returns 
YES and the field accepts the value. 

2. The NSRunAlertPanell) function allows you to display a modal attention panel 
from any point in your code. The above example calls this function simply to 
inform the user why the value cannot be accepted. 



Although Travel Advisor doesn’t evaluate it, the NSRunAlertPanell) function 
returns a constant indicating which button the user clicks on the panel. The 
logic of your code could therefore branch according to user input. In 
addition, the function allows you to insert variable information (using printfl)- 
style conversion specifiers) into the body of the message. 
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Application Management 

By now you’ve finished the major coding tasks for Travel Advisor. All that 
remains to implement are a half dozen or so methods. Some of these methods 
perform tasks that every application should do. Others provide bits of 
functionality that Travel Advisor requires. In this section you’ll: 

• Archive and unarchive the TAController object. 

• Implement TAController’s init and dealloc methods. 

• Save data when the application terminates. 

• Mark the current record when users make a change. 

• Obtain and display converted currency values. 

The data that users enter into Travel Advisor should be saved in the file system, 
or archived . The best time to initiate archiving in Travel Advisor is when the 
application is about to terminate. Earlier you made TAController the delegate 
of the application object (NSApp). Now respond to the delegate message 
applicationShouldTerminate:, which is sent just before the application terminates. 


7 Archive the application's objects 
when it terminates. 

Implement the delegate method 

applicationShouldTerminate:, as 
shown at right. 


- (BOOL)applicationShouldTerminate:(id)sender 
{ /* 1 */ 
NSString *storePath = [[[NSBundle mainBundle] bundlePath] 
stringByAppendingPathComponent:@"TravelData"]; 

/* save current record if it is new or changed */ 

[self addRecord:self]? 

/* 2 */ 

if (countryDict && [countryDict count]) 

[NSArchiver archiveRootObject:countryDict toFile:storePath] 

return YES; 

} 


1. Constructs a pathname to the application wrapper in which to store the 
archive file “TravelData.” The application wrapper—the “hidden” directory 
holding the application executable and required resources—is a bundle, so 
NSBundle methods are used to get the bundle path. 

2. If the countryDict dictionary holds Country objects, TAController archives it 
with the NSArchiver class method archiveRootObjecttoFile:. Since the dictionary 
is designated as the root object for archiving, all objects that the dictionary 
references (that is, the Country objects it contains) will be archived too. 
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8 Implement TAController's 
methods for initializing and 
deallocating itself. 

Implement the init method, as 
shown at right. 

Implement the dealloc method to 
release object instance variables. 


- (id)init 
{ 

/* 1 */ 

NSString *storePath = [[NSBundle mainBundle] 
pathForResource:@"TravelData" ofType:nil]; 

[super init]; 

/* 2 */ 

countryDict = [NSUnarchiver unarchiveObjectWithFile:storePath]; 
/* 3 */ 


if (!countryDict) 
countryDict = 
countryKeys = 

} else 

countryDict = 
recordNeedsSaving= 


{ 

[[NSMutableDictionary alloc] init]; 

[[NSMutableArray alloc] initWithCapacity:10] 

[countryDict retain]; 

NO; 


return self; 

} 


1. Using NSBundle methods, locates the archive file “TravelData” in the applicati 
wrapper and returns the path to it. 

2. The unarchiveObjectWithFile: message unarchives (that is, restores) the object whos< 
attributes are encoded in the specified file. The object that is unarchived and 
returned is the NSDictionary of Country objects (countryDict). 

3. If no NSDictionary is unarchived, the countryDict instance variable remains nil. If tl 
is the case, TAController creates an empty countryDict dictionary and an empty 
countryKeys array. Otherwise, it retains the instance variable. 


Flattening the Object Network: Coding and Archiving 



Coding, as implemented by NSCoder, takes 
a network of objects such as exist in an 
application and serializes that data, 
capturing the state, structure, relationships, 
and class memberships of the objects. As a 
subclass of NSCoder, NSArchiver extends 
this behavior by storing the serialized data 
in a file. 

When you archive a root object, you archive 
not only that object but all other objects the 
root object references, all objects those 
second-level objects reference, and so on. 
To be archived, however, objects must 
conform to the NSCoding protocol. This 
conformance requires that they implement 


the encodeWithCoder: and initWithCoder: 

methods. 

Thus sending archiveRootObject:toFile:to 
NSArchiver leads to the invocation of 
encodeWithCoder: in the root object and in 
all referenced objects that implement it. 
Similarly, sending unarchiveObjectWithFile: 
to NSUnarchiver results in initWithCoder: 
being invoked in those objects referenced in 
the archive file. These objects reconstitute 
themselves from the instance data in the file. 
In this way, the network of objects, three- 
dimensional in abstraction, is converted to 
a two-dimensional stream of data and 
back again. 
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Implementing the TAController Class 


When users modify data in fields of Travel Advisor, you want to mark the current 
record as modified so later you’ll know to save it. The Application Kit broadcasts 
a notification whenever text in the application is altered. To receive this 
notification, add TAController to the list of the notification’s observers. 


9 Write the code that marks 
records as modified. 

In the awakeFromNib method, 
make TAController an observer of 
NSControlTextDidChangeNotification. 

Implement textDidChange: to set 
the recordNeedsSaving flag. 


[[NSNotificationCenter defaultCenter] addObserver:self 
selector:©selector(textDidChange:) 

name:NSControlTextDidChangeNotification object:nil]; 

Next, implement the method that you indicated would respond to the 
notification; this method sets a flag, thereby marking the record as changed. 


You post notifications and add 
objects as observers of 
notifications with methods 
defined in the 
NSNotificationCenter class. 
NSNotification defines methods 
for creating notification objects 
and for accessing their attributes. 
See the specifications of these 
classes in the Foundation 
Framework reference 
documentation. 


- (void)textDidChange:(NSNotification *)notification 
{ 

if ([notification object] == currencyDollarsField || 
[notification object] == Celsius) return; 

recordNeedsSaving=YES; 

} 


Two of the editable fields of Travel Advisor hold temporary values used in 
conversions and so are not saved. This statement checks if these fields are the 
ones originating the notification and, if they are, returns without setting the flag. 
(The object message obtains the object associated with the notification.) 

The final method to implement is almost identical to the one you wrote for 
Currency Converter to display the results of a currency conversion when the 
user clicks the Convert button for currency conversion. 


10 Implement the method that 
responds to a request for a 
currency conversion. 


- (void)convertCurrency:(id)sender 
{ 

[currencyLocalField setFloatValue: 

[converter convertAmount:[currencyDollarsField floatValue] 
byRate:[currencyRateField floatValue]]]; 

} 


Optional Exercise - 

Convert Celsius to Fahrenheit: Implement the convertCelsius: method. You’ve already 
specified and connected the necessary outlets (celsius, fahrenheit) and action 
(convertCelsius:), so all that remains is the method implementation. The formula 
you’ll need is: 

F° = 9/5C° + 32 
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Using the Graphical Debugger 


Classes t> 

Headers F 

** Other Sources r- 

Interfaces fc 

^ Images t 

■ ■ Other ResourCpi- 
Subprojects yU 
jy Context Help — 
Supporting Fi 


Converter.m 
j Cou ntry,ni 
TAControiler.m, 



TAControiler.m 


a -control:isValidO 
-controlTextDidC 

rmmzmnz — 

;;“CpnvMCMtrency„; 


Project Builder's graphical debugger provides an 
easy-to-use, intuitive user interface to gdb, the 
GNU debugger. 

1 Launch program; run debugger; inspect 

task (breakpoints, stack, etc.) 

. . Run the application being debugged; 

interrupt and continue the application. 


frSI 1 

inferior process stopped 






(void)c! 

I 11 < 

: ES> recor 

1 H } 


IS - (BOOL)t 

Mi 


I Reading symbols from loaOTtifile...done. 

I /NextLibrary/Frameworks/Souh^Kit. framework/Versions S i WO s uw dl fo fe ■ * ' 

; 0X14000000 Offset 0X0 \ 

| Reading symbols from loaded filCTi ide n e. ■ ■ 

| /NextLibrary/Frameworks/System.framework/Versions/A/System at 0x5000000 
offset 0x0 

Reading symbols from loaded file...done. 

Apr 10 21:10:59 TravelAdvisor[8549] Could not connect the action 
switchedChecked: to target of class TAController 


— Breakpoint 1, -[TAController awakeFromNib] (self=0xl4848c, 
recor *J _ C md=0x626ef58) at TAControiler.m:255 
retur Yj (gdb) 


r I : :-v - (BOOL)applicationShouldTerminate: (id)sender 

i |||| \ 

NSString *storePath = [[[NSBundle mainBundle] bundlePath] 
tjrj ; stringByAppendingPathComponent:@"TravelData"]; 


• Print value, print referenced value, print 
object description (select variable first). 

■ Step over, step into statement. 

■ Launch options (see below) 


’ You can also issue gdb commands on the 
command line. 



Launch Optio ns 


Launch Options 


Launch Options 




Launch options affect both 
launched and debugged programs. 
The inspector displays allow you to 
set target executables, 
environment variables, and source 
directories. 


108 































































Building and Running Travel Advisor 


Building and Running Travel Advisor 

When Travel Advisor is built, start it up by double-clicking the icon in the File 

Manager. Then put the application through the following tests: 

• Enter a few records. Make up geographical information if you have to— 
you’re not trusting your future travels to this application. Not yet, anyway. 

• Click the items in the table view and notice how the selected records are 
displayed. Press Command-n and Command-r and observe what happens. 

• Enter values in the conversion fields to see how they’re automatically 
formatted. Try to enter a negative value in the Rate field. 

• Quit the application and then start it up again. Notice how the application 
displays the same records that you entered. 


Tips for Eliminating Deallocation Bugs 

Problems in object deallocation are not unusual in OpenStep 
applications under development. You might release an object too 
many times or you might not release an object as many times as 
is needed to deallocate it. Both situations lead to nasty problems 
—in the first case, to run-time errors when your code references 
non-existent objects; the second case leads to memory leaks. 

If you're releasing an object too many times, you'll get run-time 
error messages telling you that a message was sent to a freed 
object. To find which methods were releasing the object, in gdb or 
the graphical debugger:: 

1 Send enableFreedObjectCheck: to NSAutoreleasePool with 
an argument of YES. 

2 Set a breakpoint on _NSAutoreleaseFreedObject. 

3 Run the program under the debugger. 

4 When the program hits the breakpoint, do a backtrace and 
check the stack to find the method releasing the object. 

Other tools help you track down problems related to release and 
autorelease: 

• The oh command records allocation and deallocation events 
related to a specific process. It produces a report showing the 
stack frame for an object each time the object is allocated, 
copied, retained or released. 


• The AnalyzeAllocation tool compiles statistics on memory 
allocation during the time a program executes. 

See the man pages on these tools for more information. 

Avoiding Deallocation Errors 

Here's a few things to rememberthat might help you avoid 

deallocation bugs in OpenStep code: 

• Make sure there's an alloc, copy, mutableCopy, or retain 
message sent to an object for each release or autorelease 
sent to it. 

• When you release a collection object (such as an NSArray), 
you release all objects stored in it as well. When you request 
an object stored in a collection object, it's returned to you 
autoreleased. 

• Superviews retain subviews as you add them to the view 
hierarchy and release subviews as you release them. If you 
want to keep swapped-out views, you should retain them. 
Similarly, when you replace a window's or box's content view, 
the old view is released and the new view is retained. 

• To avoid retain cycles, objects should not retain their 
delegates. Objects also should not retain their outlets, since 
they do not own them. 
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Sections 


Concepts 


The design of To Do 

Setting up the project 

Creating the model class 

Subclass example: adding 
data and behavior 

The basics of a multi¬ 
document application 

Managing documents through 
delegation 

Managing the data and 
coordinating its display 

Subclass example: overriding 
behavior 

Creating and managing an 
inspector 

Subclass example: overriding 
and adding behavior 

Setting up timers for 
notification messages 

Build, run, and extend the 
application 


Starting up — what happens in NSApplicationMainO 

Dynamically loading resources and code 

Dates and times in OpenStep 

The structure of multi-document applications 

The application quartet: NSResponder, NSApplication, NSWindow, and NSView 

Coordinate systems in OpenStep 

Events and the event cycle 

A short guide to drawing and compositing 

Making a custom NSView 

Run loops and timers 
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Many kinds of applications—word processors and spreadsheets, to name a 
couple—are designed with the notion of a document in mind. A document is a 
body of information, usually contained by a window, that is self-contained and 
repeatable. Users can create, modify, store, and access a document as a discrete 
unit. Multi-document applications (as these programs are called) can generate 
an almost unlimited number of documents. 

The To Do application presented in this chapter is a multi-document 
application. It is a fairly simple personal information manager (PIM). Each To 
Do document captures the daily “must-do” items for a particular purpose. For 
instance, one could have a To Do list for work and another one for home. To Do 
allows users to: 

• Enter appointments or actions that they must complete on particular days. 

• Specify the times those items are due. 

• Receive notifications at a specified interval before the due time. 

• Associate notes with to-do items. 

• Mark items as complete or deferred. 



Inspector [ X 


Date: Tue, Jan 30 1996 
Item: board meeting 

Notification q| 


Time: 110 : |o C AM C PM 

-—-—— When to Notify —— 
_Jdo not notify 
is minutes before 
1 hour before 
1 day b efore 

Other | ; hours 


As with Travel Advisor, you’re going to cover a lot of OpenStep territory by 
completing this tutorial. It explores two major areas: 

• Multi-document architecture: The design of applications that can create 
multiple documents, save and restore those documents, and do the right 
thing on certain events, such as application termination. 
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• Strategies for subclassing: Reuse of existing classes by adding behavior and 
data, by overriding existing behavior, or by doing both things. 

You will also learn about other aspects of OpenStep programming: 

• Opening and saving files 

• Loading nib files (and other bundles) programmatically 

• Creating and managing inspectors 

• Programmatic creation and manipulation of user-interface objects 

• Time and date manipulation 

• Declaring informal protocols 

• Using timers 

And you’ll be introduced to these important OpenStep concepts: 

• Event handling 

• The core program framework 

• Drawing and image composition 

When you complete this tutorial, you should be ready to tackle OpenStep 
programming on your own. 


Starting Up — What Happens in NSApplicationMainO 

Every OpenStep application project created through Project 
Builder has the same main() function (in the file 
ApplicationNamejmain.m). When users double-click an 
application or document icon in the File Viewer, main() (the entry 
point) is called first; mainf), in turn, calls NSApplicationMainO— 
and that's all it does. 

The NSApplicationMainO function does what's necessary to get 
an OpenStep application up and running—responding to events, 
coordinating the activity of its objects, and so on. The function 
starts the network of objects in the application sending messages 
to each other. Specifically, NSApplicationMainO: 

1 Gets the application's attributes, which are stored in the 
application wrapper as a property list. From this property list, 
it gets the names of the main nib file and the principal class (for 
applications, this is NSApplication or a custom subclass of 
NSApplication). 


2 Gets the Class object for NSApplication and invokes its 
sharedApplication class method, creating an instance of 
NSApplication, which is stored in the global variable, NSApp. 
Creating the NSApplication object connects the application to 
the window system and the Display PostScript server, and 
initializes its PostScript environment. 

3 Loads the main nib file, specifying NSApp as the owner. 
Loading unarchives and re-creates application objects and 
restores the connections between objects. 

4 Runs the application by starting the main event loop. Each time 
through the loop, the application object gets the next available 
event from the Window Server and dispatches it to the most 
appropriate object in the application. The loop continues until 
the application object receives a stop: or terminate: message, 
after which the application is released and the program exits. 

You can add your own codetomain()to customize application 

start-up ortermination behavior. 
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The Design of To Do 


The To Do application vaults past Travel Advisor in terms of complexity. 
Instead of Travel Advisor’s one nib file, To Do has three nib files. Instead of 
three custom classes, To Do has seven. This diagram shows the 
interrelationships among instances of some of those classes and the nib files that 
they load: 



The ToDoInspector instance in 
the above diagram is an offshoot 
of the application controller, 
ToDoController. By breaking 
down a problem domain into 
distinct areas of responsibility, 
and assigning certain types of 
objects to each area, you increase 
the modularity and reusability of 
the object, and make 
maintenance and trouble¬ 
shooting easier. See “Object- 
Oriented Programming” in the 
appendix for more on this. 


Some of the objects in this diagram are familiar, fitting as they do into the 
Model-View-Controller paradigm. The ToDoItem class provides the model 
objects for the application; instances of this class encapsulate the data associated 
with the items appearing in documents. They also offer functions for computing 
subsets of that data. And then there’s the controller object...actually, there is 
more than one controller object. 

To Do's Multi-Document Design 

Two types of controller objects are at the heart of multi-document application 
design. They claim different areas of responsibility within an application. 
ToDoController is the application controller, it manages events that affect the 
application as a whole. Each ToDoDoc object is a document controller, and 
manages a single document, including all the ToDoItems that belong to the 
document. Naturally, it’s essential that the application controller be able to 
communicate with its (potentially) numerous document controllers, and they 
with it. 
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Only When Needed: Dynamically Loading Resources and Code 


iM 


ililli 


As any developer knows well, performance is a key consideration 
in program design. One factor is the timing of resource allocation. 
If an application loads all code and resources that it mightuse 
when it starts up, it will probably be a sluggish, bloated 
application—and one that takes awhile to launch. 

You can strategically store the resources of an application 
(including user-interface objects) in several nib files. You can also 
put code that might be used among one or more loadable bundles. 
When the application needs a resource or piece of code, it loads 
the nib file or loadable bundle that contains it. This technique of 
deferred allocation benefits an application greatly. By conserving 
memory, it improves program efficiency. Italso speeds up thetime 
it takes to launch the application. 

Auxiliary Nib Files 

When more sophisticated applications start up, they load only a 
minimum of resources in the main nib file—the main menu and 
perhaps a window. They display other windows (and load other 
nib files) only when users request it or when conditions warrant it. 

Nib files other than an application's main nib file are sometimes 
called auxiliary nib files. There are two general types of auxiliary 
nib files: special-use and document. 

Special-use nib files contain objects (and other resources) 
that might be used in the normal operation of the application. 
Examples of special-use nib files are those containing inspector 
panels and Info panels. 


nib files. The File's Owner object is not really appearing twice; it's 
created in one file and referenced in the other. 

The File's Owner object dynamically loads a nib file and makes 
itself the owner of that file by sending loadNibNamed:owner to 
NSBundle, specifying self as the second argument. 

NSBundle and Bundles 

A bundle is a location in the file system that stores code and the 
resources that go with that code, including images, sounds, and 
archived objects. A bundle is also identified with an instance of 
NSBundle, which makes the contents of the bundle available to 
other objects that request it. 

The generic notion of bundles is pervasive throughout OpenStep. 
Applications are bundles, as are frameworks and palettes. Every 
application has at least one bundle—its main bundle—which is 
the ".app" directory (or application wrapper) where its 
executable file is located. This file is loaded into memory when 
the application is launched. 

Loadable Bundles 

You can organize an application into any number of other bundles 
in addition to the main bundle and the bundles of linked-in 
frameworks. Although these loadable bundles usually reside 
inside the application wrapper, they can be anywhere in the file 
system. Project Builder allows you to build Loadable Bundle 
projects. 


Document nib files contain objects that represent some 
repeatable entity, such as a word-processor document A 
document nib file is a template for documents: it contains the Ul 
objects and other resources needed to make a document. 

The Owner of an Auxiliary Nib File 

The object that loads a nib file is usually the object that owns 
it. A nib file's owner must be external to the file. Objects 
unarchived from the nib file communicate with other objects in 
the application only through the owner. 

In Interface Builder, the File's Owner icon represents this external 
object. The File's Owner is typically the application controller for 
special-use nib files, and the document controller for document 

J " . -.iM ■ ■ : : : ■ ■■MflM 



Loadable bundles differ from nib files in thatthey don't require you 
to use Interface Builder to build them. Instead of containing 
mostly archived objects, they usually contain mostly code. 
Loadable bundles are especially useful for incorporating extra 
behavior into an application upon demand. An economic-forecast 
application, for example, might load a bundle containing the code 
defining an economic model, but only when users request that 
model. You could also use loadable bundles to integrate "plug and 
play" components into an existing framework. 

Loadable bundles usually have an extension of ".bundle" 
(although that's a convention, not a requirement). Each loadable 
bundle must have a principal class that mediates between bundle 
objects and external objects. 

< : ■| ' MIS ' v 
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As multi-document applications typically do, To Do includes the Document 
menu found on Interface Builder’s Menus palette. When users choose New 
from the Document menu, the application controller allocates and initializes an 
instance of the ToDoDoc class. When the ToDoDoc instance initializes itself, it 
loads the ToDoDoc.nib file. When the user has finished entering items into the 
document, and chooses Save from the Document menu, a Save panel appears 
and the user saves the document in the file system under an assigned name. 
Later, the user can open the document using the Open menu command, which 
causes the Open panel to be displayed. 


The rationale behind, and 
process of, constructing 
multi-document applications is 
discussed in “The Structure of 
Multi-Document Applications” 
on page 141. 


The controller objects of To Do respond to a variety of delegation messages sent 
when certain events occur—primarily from windows and NSApp—in order to 
save and store object state. One example of such an event is when the user 
closes a document window; another is when data is entered into a document. 
Often when these events happen, one controller sends a message to the other 
controller to keep it informed. 


How To Do Stores and Accesses its Data 

The data elements of a To Do document (ToDoDoc) are ToDoItems. When a 
user enters an item in a document’s list, the ToDoDoc creates a ToDoItem and 
inserts that object in a mutable array (NSMutableArray); the ToDoItem 
occupies the same position in the array as the item in the matrix’s text field. This 
positional correspondence of objects in the array and items in the matrix is an 
essential part of the design. For instance, when users delete the first entry in the 
document’s list, the document removes the corresponding ToDoItem (at index 
0) from the array. 
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The array of ToDoItems is associated with a particular day. Thus the data for a 
document consists of a (mutable) dictionary with arrays of ToDoItems for values 
and dates for keys. 


NSMutableDictionary 



When users select a day in the calendar, the application computes the date, 
which it then uses as the key to locate an array of ToDoItems in the dictionary. 


To Do's Custom Views 

The discussion so far has touched on model objects and controller objects, but 
has said nothing about the second member of the Model-View-Controller triad: 
view objects. Unlike Travel Advisor, which uses only “off-the-shelf’ views, To 
Do’s interface features objects from three custom Application Kit subclasses. 



4 January 1996 ► 

Sun Mon Tue Wed Thu Fri Sat 


CalendarMatrix: a 
subclass of NSMatrix, 
this is a dynamic 
calendar that notifies 
the delegate about 
selected dates. 


26 29 30 31 


ToDoCell: a subclass of 
NSButtonCell, this is a tri¬ 
state control with 
different images for each 
state. It also displays 
times items are due. 


Status/Due To Do on Tue Januyy 30 1996 
■X io ooAM | | board meeting ^ 

12:30AM 11 lunch with Senator F. 


SelectionNotifMatrix: 
modifies NSMatrix to 
notify observers when a 
selection in a text field 
occurs. 


You’ll learn much more about these custom subclasses in the pages that follow. 
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Setting up the To Do Project 


1 Create the application project. 

Start Project Builder. 

Choose New from the Project 
menu. 


Create the To Do project almost in the same way you created the Travel Advisor 
application. There are a few differences; each, of course, has a different name 
and icon. But the most important difference is that To Do has its own document 
type. 


Name the application "ToDo." 


2 Add the application icon. 

The ToDo icon (ToDo.tiff) is 
located in the ToDo project in the 
AppKit subdirectory of 

/NextDeveloper/Examples. 



You can have different icons and other project 
attributes for OpenStep for Mach and 
OpenStep for Windows. 


Instead of dragging the image-file icon into 
the well, you can add the image file to the 
(project and then just type the name of the 
image here. 


3 Specify the To Do document type. 

Click Add. 

Double-click the new cell under 
the Extension column. 

Type the extension of To Do 
documents: "td". 

Drag into the image well the file 
calendar.tiff from the ToDo 
project in 

/NextDeveloper/Examples/ 

AppKit. 


j fprojectAiributes 


Project Name:) ToDo 


Language:] English__ 
Application CI as s: | N S A p piicatio n 


Main Nib File: ToDo 


! [OPENSTEP for MacF~' ~ 


S Help File 

i : i 

!~|ii 

Application Icon 

l r ..... 

r t 


: ToDo.tiff 


| Documcntlcons 


EPHEI 

td calendar.tiff 


icon MameJUi 


i Add 


; Remove 


Document types specify the kinds of files the 
application can open and "understand." They 
appear in the workspace with the assigned icon 
and may be opened by double-clicking. 


As with the application icon, when you drag 
the document icon into the image well, the image 
file is added to the project. 


Before Project Builder accepts the document icon, 
you must assign the extension (if the type is new) 
and select the row. 

If the document type is well-known (for example, 
“.c"), just drag a document of that type into the well. 
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Creating the Model Class (ToDoltem) 


The ToDoltem class provides the model objects for the To Do application. Its 
instance variables hold the data that defines tasks that should be done or 
appointments that have to be kept. Its methods allow access to this data. In 
addition, it provides functions that perform helpful calculations with that data. 
ToDoltem thus encapsulates both data tf/^behavior that goes beyond accessing 
data. 

Since ToDoltem is a model class, it has no user-interface duties and so the 
expedient course is to create the class without using Interface Builder. We first 
add the class to the project; Project Builder helps out by generating template 
source-code files. 


1 Add the ToDoltem class to the 
project. 

Select Classes in the project 
browser. 

Choose New In Project from the 
File menu. 

In the New File In ToDo panel, 
type "ToDoltem" in the Name 
field. 

Make sure the "Create header" 
switch is checked. 

Click the OK button. 



As you’ve done before with Travel Advisor, start by declaring instance variables 
and methods in the header file, ToDoltem.h. 


2 Declare ToDoltems instance 
variables and methods. 

Type the instance variables as 
shown at right. 

Indicate the protocols adopted by 
this class. 


©interface ToDoltem:NSObject<NSCoding, NSCopying> 
{ 

NSCalendarDate *day; 

NSString *itemName; 

NSString *notes; 

NSTimer *iteraTimer; 
long secsUntilDue; 
long secsUntilNotif; 

ToDoItemStatus itemStatus; 

} 


You are adopting the NSCopying protocol in addition to the NSCoding protocol 
because you are going to implement a method that makes “snapshot” copies of 
ToDoltem instances. 
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3 Define enum constants for use in 
ToDoltems methods. 

Definethese constants before the 
©interface directive. 


4 Declare two time-conversion 
functions. 


Instance Variable 

What it Holds 

day 

The day (a date resolved to 12:00 AM) of the to-do item 

itemName 

The name of the to-do item (the content's of a document text field) 

notes 

The contents of the inspector's Notes display; this could be any 
information related to the to-do item, such as an agenda to discuss at 
a meeting. 

itemTimer 

A timer for notification messages. 

secsUntilDue 

The seconds after day at which the item comes due 

secsUntilNotif 

The seconds after day at which a notification is sent (before 
secsUntilDue) 

itemStatus 

Either "incomplete," "complete," or "deferToNextDay" 


typedef enum _ToDoItemStatus { 
incomplete=0, 
complete, 
de ferToNextDay 
} ToDoltemStatus; 

enum { 

minlnSecs = 60, 
hrlnSecs = (minlnSecs * 60) , 
daylnSecs = (hrlnSecs * 24), 
weeklnSecs = (daylnSecs * 7) 

}; 


The first set of constants are values for the itemStatus instance variable. The 
second set of constants are for convenience and clarity in the methods that deal 
with temporal values. 

BOOL ConvertSecondsToTime(long secs, int *hour, int *minute); 
long ConvertTimeToSeconds(int hr, int min, BOOL flag); 


These functions provide computational services to clients of this class, 
converting time in seconds to hours and minutes (as required by the user 
interface), and back again to seconds (as stored by ToDoltem). 
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Type the method declarations 
shown at right. 


5 Implement accessor methods. 

Open ToDoltem.m in the code 
editor. 

Implement methods that get and 
set the values of ToDoltem's 
instance variables. 

Implement the setltemllmer: 
method as shown at right. 


Timers (instances of NSTimer) 
are always associated with a run 
loop (an instance of 
NSRunLoop). See “Tick Tock 
Brrrring: Run Loops and Timer” 
on page 190 for more on timers 
and run loops. 


- 


{id)initWithName:(NSString *)name andDate:(NSCalendarDate *)date; 
(void)dealloc; 

(BOOL)isEqual:(id)anObject; 

(id)copyWithZone:(NSZone *)zone; 

(id)initWithCoder:(NSCoder *)coder; 

(void)encodeWithCoder:(NSCoder *)coder; 

(void)setDay:(NSCalendarDate *)newDay; 

(NSCalendarDate *)day; 

(void)setltemName:(NSString *)newName; 

(NSString *)itemName; 

(void)setNotes:(NSString *)notes; 

(NSString *)notes; 

(void)setltemTimer:(NSTimer *)aTimer; 

(NSTimer *)itemTimer; 

(void)setSecsUntilDue:(long)secs; 

(long)secsUntilDue; 

(void)setSecsUntilNotif:(long)secs; 

(long)secsUntilNotif; 

(void)setltemStatus:(ToDoItemStatus)newStatus; 

(ToDoItemStatus)itemStatus; 


Most of these declarations are for accessor methods. You know what to do. 


(void)setltemTimer:(NSTimer *)aTimer 


if (itemTimer) { 

[itemTimer invalidate]; 
[itemTimer autorelease]; 

> 

itemTimer = [aTimer retain]; 


The setltemTimer: method is slightly different from the other “set” accessor 
methods. It sends invalidate to itemTimer to disable the timer before it autoreleases 
it. 

In this application, you want client objects to be able to copy your ToDoItem 
objects and test them for equality. You must define this behavior yourself. 


124 









Creating the Model Class (ToDoltem) 


6 Implement the isEqual: method. 


7 Implement the copyWithZone: 
method. 


Copies of objects can be either 
deep or shallow. In deep copies 
(like ToDoItem’s) every copied 
instance variable is an 
independent replicate, including 
the values referenced by 
pointers. In shallow copies, 
pointers are copied but the 
referenced objects are the same. 
For more on this topic, see the 
description of the NSCopying 
protocol in the Foundation 
reference documentation. 


- (BOOL)isEqual:(id)anObj 
{ 

if ([anObj isKindOfClass:[ToDoltem class]] && 

[itemName isEqualToString:[anObj itemName]] && 

[day isEqualToDate:[anObj day]]) 
return YES; 

else 

return NO; 

} 

The default implementation of isEqual: (in NSObject) is based on pointer 
equality. However, ToDoltem has a different basis for equality; any two 
ToDoltem objects for the same calendar day and having the same item name are 
considered equal. The implementation of isEqual: overrides NSObject to make 
these tests. (Note that it invokes NSString’s and NSDate’s own isEqual... 
methods for the specific tests.) 

Before You Go On - 

There is a specific as well as a general need for the isEqual: override. In the To 
Do application, an NSArray contains a day’s ToDoItems. To access them, other 
objects in the application invoke several NSArray methods that, in turn, invoke 
the isEqual: method of each object in the array. 


- (id)copyWithZone:(NSZone *)zone 
{ 

ToDoltem *newobj = [[ToDoltem alloc] initWithName:itemName 
andDate:day]; 

[newobj setNotesmotes]; 

[newobj setltemStatus:itemStatus]; 

[newobj setSecsUntilDue:secsUntilDue]; 

[newobj setSecsUntilNotif:secsUntilNotif]; 


return newobj; 


This implementation of the copyWithZone: protocol method makes a copy of a 
ToDoltem instance that is an independent replicate of the original (self). It does 
this by allocating a new ToDoltem object and initializing it with the essential 
instance variables held by self. Copying is often implemented for value objects— 
objects that represent attributes such as numbers, dates, and to-do items. 


The next method you’ll implement— description —assists you and other 
developers in debugging the To Do application with gdb. When you enter the po 
(print object) command in gdb with a ToDoltem as the argument, this description 
method is invoked and essential debugging information is printed. 
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8 Implement the description 
method. 


9 Implement ToDoltem's initializing 
and deallocation methods. 


10 Implement ToDoltem's archiving 
and unarchiving methods. 


- (NSString *)description 

i 

NSString *desc = [NSString stringWithFormat: @" %@\n\tName: %@\n\tDate: 
%@\n\tNotes: %@\n\tCompleted: %@\n\tSecs Until Due: %d\n\tSecs Until 
Notif: %d" / 

[super description], 

[self itemName], 

[self day], 

[self notes], 

{([self itemStatus]==complete)?@"Yes":@"No"), 

[self secsUntilDue], 

[self secsUntilNotif]]; 

return (desc); 

} 

Here are some things to remember as you implement initWithName:andDate: and 
dealloc: 

• If the first argument of initWithlMame:andDate: (the item name) is not a valid 
string, return nil. If the second argument (the date) is nil, set the related 
instance variable to some reasonable value (such as today’s date). Also, be sure 
to invoke super’s init method. 

• The instance variables to initialize are day, itemName, notes, and itemStatus (to 
“incomplete”). 

• In dealloc, release those object instance variables initialized in 
initWithName:andDate: plus any object instance variables that were initialized 
later. Also invalidate any timer before you release it. 

When you implement encodeWithCoder: and initWithCoder:, keep the following in 
mind: 

• Encode and decode instance variables in the same order. 

• Copy the object instance variables after you decode them. 

• You don’t need to archive the itemTimer instance variable since timers are re¬ 
set when a document is opened. 

The final step in creating the ToDoItem class is to implement the functions that 
furnish “value-added” behavior. 
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11 Implement ToDoltem's time- 
conversion functions. 


long ConvertTimeToSeconds(int hr, int min, BOOL flag) /* 1 */ 

{ 

if (flag) { /* PM */ 

if (hr >= 1 && hr < 12) 
hr += 12; 

} else { 

if (hr == 12) 
hr = 0 ; 

} 

return ((hr * hrlnSecs) + (min * minlnSecs)); 

} 

BOOL ConvertSecondsToTime(long secs, int *hour, int *minute) /* 2 */ 

{ 

int hr=0; 

BOOL pm=NO; 

if (secs) { 

hr = secs / hrlnSecs; 
if (hr > 12) { 

*hour = (hr -= 12); 
pm = YES; 

} else { 

pm = NO; 
if (hr == 0) 
hr = 12; 

*hour = hr; 

} 

*minute = ((secs%hrInSecs) / minlnSecs); 

} 

return pm; 

■ > 

1. This expression, as well as others in these two methods, uses the enum constants 
for time-values-as seconds that you defined earlier. 

2. The ConvertSecondsToTimef) function uses indirection as a means for returning 
multiple values and directly returns a Boolean to indicate AM or PM. 
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Subclass Example: Adding Data and Behavior (CalendarMatrix) 

The calendar on To Do’s interface is an instance of a custom subclass of 
NSMatrix. CalendarMatrix dynamically updates itself as users select new 
months, notifies a delegate when users select a day, and reflects the current day 
(today) and the current selection by setting button attributes. 
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Creating a subclass of a class that is farther down the inheritance tree poses more 
of a challenge for a developer than a simple sublcass of NSObject. A class such 
as NSMatrix is more specialized than NSObject and carries with it more 
baggage: It inherits from NSResponder, NSView, and NSControl, all fairly 
complex Application Kit classes. And since CalendarMatrix inherits from 
NSView, it appears on the user interface; it is an example of a view object in the 
Model-View-Controller paradigm, and as such it is highly reusable. 

Why NSMatrix? 

When you select a specialized superclass as the basis for your subclass, it is 
important to consider what your requirements are and to understand what the 
superclass has to offer. To Do’s dynamic calendar should: 

• Arrange numbers (days) sequentially in rows and columns. 

• Respond to and communicate selections of days. 

• Understand dates. 

• Enable navigation between months. 

If you then started to peruse the reference documentation on Application Kit 
classes, and looked at the section on NSMatrix, you’d read this: 

NSMatrix is a class usedfor creating groups of NSCells that work together in various 
ways. It includes methods for arranging NSCells in rows and columns .... An 
NSMatrix adds to NSControl's targetlaction paradigm by allowing a separate target 
and action for each of its NSCells in addition to its own target and action. 
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1 Define the CalendarMatrix class 
in Interface Builder. 

From Project Builder, open 

ToDo.nib. 

In Interface Builder, choose 
Document ► New Module ► 
New Empty to create a new nib 
file. 

Save the nib file as ToDoDoc.nib. 

In the Classes display of the nib 
file window, select NSMatrix. 

Choose Subclass from the pull¬ 
down list. 

Name the new class 
"CalendarMatrix". 

Select the new class. 

Add the outlets and actions 
shown in the example at right. 


So NSMatrix has an inherent capability for the first of the requirements listed 
above, and part of the second (responding to selections). Our CalendarMatrix 
subclass thus does not need to alter anything in its superclass. It just needs to 
supplement NSMatrix with additional data and behavior so it can understand 
dates (and update itself appropriately), navigate between months, and notify a 
delegate that a selection was made. 
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Locate NSMatrix several levels down in the 
class hierarchy. 


Outlets and actions already defined by the 
superclass (or its superclasses) appear in 
gray text. Add the outlets and actions shown 
in black text. 


When you created subclasses of NSObject in the previous two tutorials, the next 
step was to instantiate the subclass. Because CalendarMatrix is a view (that is, it 
inherits from NSView), the procedure for generating an instance for making 
connections is different. 
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2 Put a custom NSView object 
(CalendarMatrix) on the user 
interface. 

Drag awindowfromthe Windows 
palette. 

Resize the window, using the 
example at right as a guide. 

Turn off the window's resize 
handle. 

Drag a CustomView from the 
Views palette onto the window. 

Resize and position the 
CustomView, using the example 
at right as a guide. 

In the Attributes display of the 
inspector, select CalendarMatrix 
from the list of available classes. 



The selection of the class for the CustomView creates an instance of it that you 
can connect to other objects in the nib file. Now put the controls and fields 
associated with CalendarMatrix on the window. 
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3 Put the objects related to 

CalendarMatrix on the window. 

Drag a label objectforthe month- 
year from the Views palette and 
put it over the CalendarMatrix. 

Make seven small labelsfor each 
day of the week. 

Drag a button onto the interface 
and set its attributes to 
unbordered and image only. 

Drag left_arrow.tiff from 
/NextDeveloper/Examples 
/AppKit/ToDo and drop it over the 
button. 

To the attention panel that asks 
"Insert image left_arrow in 
project?" click Yes. 

Repeat the same button 
procedure for right_arrow.tiff. 



Next connect CalendarMatrix to its satellite objects. 


4 Connect CalendarMatrix to its 
outlet and to the controls sending 
action messages. 

5 Finish up in Interface Builder. 

SaveToDoDoc.nib. 

Select CalendarMatrix and in the 
Classes display and choose 
Create Files from the Operations 
pull-down menu. 

Confirm that you want the source- 
code files added to the project. 


Name 

Connection 

Type 

monthName 

From CalendarMatrix to the label field above it 

outlet 

leftButton 

From CalendarMatrix to the left-pointing arrow 

outlet 

rightButton 

From CalendarMatrix to the right-pointing arrow 

outlet 

monthChanged: 

From both arrows to CalendarMatrix 

action 


You might have noticed that there’s an action message left unconnected: 
choseDay:. Because it is impossible in Interface Builder to connect an object with 
itself, you will make this connection programmatically. 


131 





Chapter 4 


To Do Tutorial 


6 Add declarations to the header 
file CalendarMatrix.h. 

(Existing declarations are 
indicted by ellipsis.) 


©interface CalendarMatrix : NSMatrix 

{ 

/* •.. */ 

NSCalendarDate *selectedDay; 
short startOffset; 

> 

/* ... */ 

- (void)refreshCalendar; 

- (id)initWithFrame:(NSRect)frameRect; 

- (void)dealloc; 

- (void)setSelectedDay:(NSCalendarDate 

- (NSCalendarDate *)selectedDay; 

©end 


; 


) newDay; 




/* i */ 


©interface NSObject(CalendarMatrixDelegate) 

- (void)CalendarMatrix:(CalendarMatrix *)obj 

didChangeToDate:(NSDate *)date; 

- (void)CalendarMatrix:(CalendarMatrix *)obj 

didChangeToMonth:(int)mo year:(int)yr; 

©end 


/* 2 */ 


There are a couple of interesting things to note about these declarations: 

1. The cells in CalendarMatrix are sequentially ordered by tag number, left to right, 
going downward. startOffset marks the cell (by its tag) on which the first day of the 
month falls. 

2. CalendarMatrixDelegate is a category on NSObject that declares the 
methods to be implemented by the delegate. This technique creates what is 
called an informal protocol, which is commonly used for delegation methods. 
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7 Implement CalendarMatrix's 
initialization methods. 

Select CalendarMatrix.m in the 
project browser. 

Write the implementation of 
initWithFrame: (at right). 

Implement dealloc. 


- (id)initWithFrame:(NSRect)frameRect 
{ 

int i, j , cnt=0; 

id cell = [[NSButtonCell alloc] initTextCell:@""]; 

NSCalendarDate *now = [NSCalendarDate date]; /* 1 */ 

[super initWithFrame:frameRect /* 2 */ 

mode:NSRadioModeMatrix 
prototype:cell 
numberOfRows:6 
numberOfColumns:7]; 

// set cell tags /* 3 */ 

for (i=0; i<6; i++) { 

for {j = 0; j <7; j++) { 

[[self cellAtRow:i column:j] setTag:cnt++]; 

} 

} 

[cell release]; 

selectedDay = [[NSCalendarDate dateWithYear:[now yearOfCommonEra] 
month:[now monthOfYear] /* 4 */ 

day:[now dayOfMonth] 
hour:0 minute:0 second:0 
. timeZone:[NSTimeZone localTimeZone]] copy]; 

return self; 

} 


The initWithFrame: method is an initializer of NSMatrix, NSControl and NSView. 

1. This invocation of date, a class method declared by NSDate, returns the current 
date (“today”) as an NSCalendarDate. (NSCalendarDate is a subclass of NSDate.) 

2. This message to super (NSMatrix) sets the physical and cell dimensions of the 
matrix, identifies the type of cell using a prototype (an NSButtonCell), and 
specifies the general behavior of the matrix: radio mode, which means that 
only one button can be selected at any time. 

3. Set the tag number of each cell sequentially left to right and down. Tags are 
the mechanism by which CalendarMatrix sets and retrieves the day numbers 
of cells. 

4. This NSCalendarDate class method initializes the selectedDay instance 
variable to midnight of the current day, using the year, month, and day 
elements of the current date. The localTimeZone message obtains an 
NSTimeZone object with an suitable offset from Greenwich Mean Time. 
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Implement awakeFromNib as - (void) awakeFromNib 

shown at right. { 

[monthName setAlignment:NSCenterTextAlignment3; 

[self setTarget:self]; 

[self setAction:©selector(choseDay:)]; 

[self setAutosizesCells:YES]; 

[self refreshCalendar]; 

■ > 

The awakeFromNib method performs additional initializations (some of which 
could just have easily been done in initWithFrame:). Most importantly, it sets self as 
its own target object and specifies an action method for this target, choseDay:, 
something that couldn’t be done in Interface Builder. Other methods to note: 

• setAutosizesCells: causes the matrix to resize its cells on every redraw. 

• refreshCalendar (which you’ll write next) updates the calendar. 

The refreshCalendar method is fairly long and complex—it is the workhorse of the 
class—so you’ll approach it in sections. 



Dates and Times in OpenStep 

In OpenStep you represent dates and times as objects that inherit 
from NSDate. The major advantage of dates and times as objects 
is common to all objects that represent basic values: they yield 
functionality that, although commonly found in most operating 
systems, is not tied to the internals of any particular operating- 
system. 

NSDates hold dates and times as values of type NSTimelnterval 
and express these values as seconds. The NSTimelnterval type 
makes possible a wide and fine-grained range of date and time 
values, giving accuracy within milliseconds for dates 10,000years 
apart. 

NSDate and its subclasses compute time as seconds relative to 
an absolute reference date (the first instant of January 1,2001). 
NSDate converts all date and time representations to and from 

NSTimelnterval values that are relative to this reference date. 

: ; V 

NSDate provides methods for obtaining NSDate objects 
(including date, which returns the current date and time as an 
NSDate), for comparing dates, for computing relative time values, 
and for representing dates as strings. 


The NSCalendarDate class, which inherits from NSDate, 
generates objects that represent dates conforming to western 
calendrical systems. NSCalendarDate objects also adjust the 
representations of dates to reflect their associated time zones. 
Because of this, you can track an NSCalendarDate object across 
different time zones. You can also present date information from 
time-zone viewpoints other than the one for the current locale. 

Each NSCalendarDate object also has a calendar format string 
bound to it This format string contains date-conversion specifiers 
that are very similar to those used in the standard C library 
function strftime(). NSCalendarDate can interpret user-entered 

dates that conform to this format string. 

' 

NSCalendar has methods for creating NSCalendarDate objects 
from formatted strings and from component time values (such as 
minutes, hours, day of week, and year). It also supplements 
NSDate with methods for accessing component time values and 
for representing dates in various formats, locales, and time zones. 
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8 Implement the code that updates 
the calendar. 

Initialize the MonthDays[] array 
and write the isLeapO macro. 

Determine the day of the week at 
the start of the month and the 
number of days in the month. 


static short MonthDays[] = 

{31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31 }; 

#define isLeap(year) ({(((year) % 4) == 0 && (((year) % 100) ! = 0)) 

| | ((year) % 400) == 0) ) 


- (void)refreshCalendar 
( 

NSCalendarDate *firstOfMonth, *selDate = [self selectedDay], 
*now - [NSCalendarDate date]; 
int i, j, currentMonth = [selDate monthOfYear]; 
unsigned int currentYear = [selDate yearOfCommonEra]; 
short daysInMonth; 
id cell; 


firstOfMonth - [NSCalendarDate dateWithYear:currentYear /* 1 */ 

month:currentMonth 

day:l hour:0 minute:0 second:0 
timeZone:[NSTimeZone localTimeZone]]; 

[monthName setStringValue:[firstOfMonth /* 2 */ 

descriptionWithCalendarFormat:@"%B %Y"]]; 
daysInMonth = MonthDays[currentMonth-1]+1; /* 3 */ 

/* correct Feb for leap year */ 

if ((currentMonth == 2) && (isLeap(currentYear))) daysInMonth++; 
startOffset = . [firstOfMonth dayOfWeek]; /* 4 */ 


Before it can start writing day numbers to the calendar for a given month, 

CalendarMatrix must know what cell to start with and how many cells to fill with 

numbers. The refreshCalendar method begins by calculating these values. 

1. Creates an NSCalendarDate for the first day of the currently selected month and 
year (computed from the selectedDay instance variable). 

2. Writes the month and year (for example, “February 1997”) to the label above 
the calendar. 

3. Gets from the MonthDays static array the number of days for that month; if the 
month is February and it is a leap year, this number is adjusted. 

4. Gets the day of the week for the first day of the month and stores this in the 
startOffset instance variable. 
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Write the refreshCalendar code 
that writes day numbers to the 
cells and sets cell attributes. 


for (i = 0; i<startOffset; i++) { 
cell = [self cellWithTag:i]; 

[cell setBordered:NO]; 

[cell setEnabled:NO]; 

[cell setTitle:"]; 

[cell setCellAttribute:NSCellHighlighted to:NO]; 

} 

for (j=l; j < daysInMonth; i++, j++) { 

cell = [self cellWithTag:i]; 

[cell setBordered:YES]; 

[cell setEnabled:YES]; 

[cell setFont:[NSFont systemFontOfSize:12]]; 

[cell setTitle:[NSString stringWithFormat:@"%d", j J ] ; 

[cell setCellAttribute:NSCellHighlighted to:NO]; 

} 

for (;i<42;i++) { 

cell = [self cellWithTag:i]; 

[cell setBordered:NO]; 

[cell setEnabled:NO]; 

[cell setTitie:@""]; 

[cell setCellAttribute:NSCellHighlighted to:NO]; 

} 

The first and third for-loops in this section of code clear the leading and trailing 
cells that aren’t part of the month’s days. Because the current day is indicated by 
highlighting, they also turn off the highlighted attribute. The second for-loop 
writes the day numbers of the month, starting at startOffset and continuing until 
daysInMonth, and resets the font (since the selected day is in bold face) and other 
cell attributes. 


Complete the refreshCalendar 
method implementation by 
resetting the "today" cell 
attribute. 


if ({currentYear == [now yearOfCommonEra]) 

&& (currentMonth == [now monthOfYear])) { 

[[self cellWithTag:([now dayOfMonth]+startOffset)-1] 
setCellAttribute:NSCellHighlighted to:YES]; 

[[self cellWithTag:([now dayOfMonth]+startOffset)-1] 
setHighlightsBy:NSMomentaryChangeButton]; 

} 


1 


1 f 


This final section of refreshCalendar determines if the newly selected month and 
year are the same as today’s, and if so highlights the cell corresponding to today. 


136 




Subclass Example: Adding Data and Behavior (CalendarMatrix) 


9 Implement the monthChanged: 
action method. 


- (void)monthChanged:sender 
{ 

NSCalendarDate *thisDate = [self selectedDay]; 
int currentYear = [thisDate yearOfCommonEra]; 
unsigned int currentMonth = [thisDate monthOfYear]; 

if (sender == rightButton) { /* 1 */ 

if (currentMonth ==12) { 

currentMonth = 1; 
currentYear++; 

} else { 

currentMonth++; 

} 

} else { 

if (currentMonth == 1) { 

currentMonth = 12; 
currentYear—; 

} else { 

currentMonth--; 

} 

} /* 2 */ 
[self setSelectedDay:[NSCalendarDate dateWithYear:currentYear 
month:currentMonth 

day:l hour:0 minute:0 second:0 
timeZone:[NSTimeZone localTimeZone]]]; 

[self refreshCalendar]; 

[[self delegate] calendarMatrix:self /* 3 */ 

didChangeToMonth:currentMonth year:currentYear]; 

} 


The arrow buttons above CalendarMatrix send it the monthChanged: message 
when they are clicked. This method causes the calendar to go forward or 
backward a month. 

1. Determines which button is sending the message, then increments or decrements 
the month accordingly. If it goes past the end or beginning of the year, it 
increments or decrements the year and adjusts the month. 

2. Resets the selectedDay instance variable with the new month (and perhaps 
year) numbers and invokes refreshCalendar to display the new month. 

3. Sends the calendarMatrlx:didChangeToMonth:year: message to its delegate (which 
in this application, as you’ll soon see, is a ToDoDoc controller object). 
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10 Implement the choseDay: action 
method. 


11 Implement accessor methods for 
the selectedDay instance 
variable. 


- (void)choseDay:sender 
{ 

NSCalendarDate *selDate, *thisDate = [self selectedDay]; 

/* 1 */ 

unsigned int selDay = [[self selectedCell] tag]-startoffset+1; 

/* 2 */ 

selDate = [NSCalendarDate dateWithYear:[thisDate yearOfCommonEra] 

month:[thisDate monthOfYear] 
dayrselDay 
hour:0 
minute:0 
second:0 

timeZone:[NSTimeZone localTimeZone]]; 

/* 3 */ 

[[self cellWithTag:[thisDate dayOfMonth]+startOffset-1] 
setFont:[NSFont systemFontOfSize:12]]; 

[[self cellWithTag:selDay+startOffset-1] setFont: 

[NSFont boldSystemFontOfSize:12]]; 

/* 4 */ 

[self setSelectedDay:selDate]; 

[[self delegate] calendarMatrix:self didChangeToDate:selDate]; 

} 

This method is invoked when users click a day of the calendar. 

1. Gets the tag number of the selected cell and subtracts the offset from it (plus one 
to adjust for zero-based indexing) to find the number of the selected day. 

2. Derives an NSCalendarDate that represents the selected date. 

3. Sets the font of the previously selected cell to the normal system font 
(removing the bold attribute) and puts the number of the currently selected 
cell in bold face. 

4. Sets the selectedDay instance variable to the new date and sends the 

calendarMatrix-.didChangeToDate: message to the delegate. 

You are finished with CalendarMatrix. If you loaded ToDoDoc.nib right now, the 
calendar would work, up to a point. If you clicked the arrow buttons, 
CalendarMatrix would display the next or previous months. The days of the 
month would be properly set out on the window, and the current day would be 
highlighted. 

But not much else would happen. That’s because CalendarMatrix has not yet 
been hooked up to its delegate. 
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The Basics of a Multi-Document Application 


A multi-document application, as described on page 141, has at least one 
application controller and a document controller for each document opened. 
The application controller also responds to user commands relating to 
documents and either creates, opens, closes, or saves a document. 


1 Customize the applications main 
menu. 

Open ToDo.nib in Interface 
Builder. 

Drag the Document item from the 
Menus palette and drop it 
between the Info and the Edit 
submenus. 

Drag the Item item from the 
Menus palette and drop it 
between the Edit and Windows 
menus. 

Change the title of "Item" to 
"Inspector." 
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Customize the Document submenu by deleting 
the Save As, Save To, Save All, and Revert To 
Saved commands. 


Append an ellipsis (three dots) to the command 
name to indicate that the command displays a 
panel. Also enter "/" as the key equivalent. 


Note: The Info submenu, which you get by default, includes the Info Panel, 
Preferences, and Help commands. Although this tutorial does not cover 
implementing Info and Preferences panels specifically, it does give you enough 
information (which it will supplement with tips) so that you can try to 
implement these panels on your own. You may delete the Help command from 
the Info submenu if you wish; if you leave it in and users click it, they get a 
message informing them that Help is not available. 


2 Define the application-controller 
class. 

Create ToDoController as a 
subclass of NSObject. 

Add the outlet and actions (listed 
at right) to the class. 

Make the action connections 
from the appropriate Document 
menu commands. 



Classes 


o ToDoCdntroller 

Outlets 

inspector 

Actions 


closeDoc: 

newDo WSSS1 

openDoc: 

saveDoc: 

showinfo: 

showlnspector: 

showPreferences: 


ToDo.nib-/Projects/To Do-3/English.lproj 



Now that you’ve defined the application-controller class, define the document- 
controller class, ToDoDoc. Remember, since the ToDoDoc controller must own 
the nib file containing the document, it must be external to it; although it is 
defined in the main nib file (ToDo.nib) and in ToDoDoc.nib, it’s instantiated before 
its nib file is loaded. 
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3 Define the document-controller 
class. 

Create ToDoDoc as a subclass of 
NSObject. 

Add to the class the outlets and 
action listed at right. 

Instantiate ToDoController and 
ToDoDoc. 

SaveToDo.nib. 



Classes 


O ToDoDoc 

Outlets 
calendar 
dayLabel 
item Matrix 
markMatrix 

Actions __ 

itemChecked: 


Operations rj 


Now add the remaining objects to the document interface. 


4 Complete the document 
interface. 

OpenToDoDoc.nib. 

Add the matrices of text fields. 

Add the labels above the 
matrices. 

Make the labels 14 points in the 
user's application font. 

Make the item text 12 points in the 
user's application font. 

Save ToDoDoc.nib. 


r x 



Add padding to this label, 
extending it acrss the 
column. 


Remember, create a matrix 
by Alternate-dragging a 
handle of a suitable object. 
Before Alternate-dragging, 
make the initial text field 
scrollable. 


5 Connect the outlets and actions 
of ToDoDoc. 

Select File's Owner in the 
Instances display of 

ToDoDoc.nib. 

Choose ToDoDoc from the list of 
classes in the Attributes display 
of the inspector. 

Make the connections described 
in the table at right. 


Name 

Connection 

Type 

calendar 

From File's Owner to the CalendarMatrix object 

outlet 

dayLabel 

From File's Owner to label "To Do on" 

outlet 

item Matrix 

From File's Owner (ToDoDoc) to matrix of long text fields outlet 

markMatrix 

From File's Owner to matrix of short text fields 

outlet 

itemChecked: 

From matrix of short text fields to File's Owner 

action 
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The Structure of Multi-Document Applications 


From a user's perspective, a document is a unique body of 
information usually contained by its own window. Users can 
create an unlimited number of documents and save each to a file. 
Common documents are word-processing documents and 
spreadsheets. 

From a programming perspective, a document comprises the 
objects and resources unarchived from an auxiliary nib file and 
the controller object that loads and manages these things. This 
document controller\s the owner of the auxiliary nib file 
containing the document interface and related resources.To 
manage a document, the document controller makes itself the 
delegate of its window and its "content" objects. Ittracks edited 
status, handles window-close events, and responds to other 
conditions. 

When users choose the New (or equivalent) command, a method 
is invoked inthe application's controller object. In this method,the 
application controller creates a document-controller object, 
which loadsthe document nibfile inthe course of initializing itself. 
A documentthus remains independent of the application's "core" 
objects, storing state data inthe document controller. If the 
application needs information about a document's state, it can 
query the document controller. 

When users chose the Save command, the application displays a 
Save panel and enables users to save the document in the file 
system. When users chose the Open command, the application 
displays an Open panel, allowing users to select a document file 
and open it. 

Document Management Techniques 

When you make the application controller and the document 


controller delegates of the application (NSApp) and the document 
window, they can receive messages sent at critical moments of a 
running application. These moments include the closure of 
windows (windowShouldClose:), window selection 
(windowDidResignMain:), application start-up 
(applicationWillFinishLaunching:) and application termination 
(applicationShouldTerminate:). In the methods handling these 
messages,the controllers canthen dothe appropriate thing, such 
as saving a document's data or displaying an empty document. 

Several NSViews also have delegation messages that facilitate 
document management, particularly text fields, forms, and other 
controls with editable text (controlText...) and NSText objects 
(text...). One important such message is textDidChange: (or 
controlTextDidChange:), which signals that the document's 
textual content was modified. In responding to this message, 
controllers can setthe window's close button to have a "broken" 
X with the setDocumentEdited: message; later, they can 
determine whether the document needs to be saved by sending 
isDocumentEdited to the window. 

Document controllers often need to communicate with the 
application controller or other objects inthe application. One way 
to do this is by posting notifications. Another way is to use the key 
relationships within the core program framework (see page 149) 
to find the other object (assuming it's a delegate of an Application 
Kit object). For example, the application controller can send the 
following message to locate the current document controller: 

[[NSApp mainWindow] delegate] 

The document controller can find the application controller with: 

[NSApp delegate] 


Document Creation Sequence 
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Text fields in a matrix, just like a form’s cells, are connected for inter-field 
tabbing when you create the matrix. But you must also connect ToDoDoc and 
ToDoController to the delegate outlets of other objects in the application—this 
step is critical to the multi-document design. 


Connect ToDoDoc and 
ToDoController to other objects 
as their delegates. 


Name 

Connection 

textDelegate 

From the CalendarMatrix object to File's Owner (ToDoDoc) 

delegate 

From the document window's title bar to File's Owner (ToDoDoc) 

delegate 

In ToDo.nib, from File's Owner (NSApp) to the ToDoController instance 


6 Create source-code files for 
ToDoDoc and ToDoController. 


The ToDoDoc class needs supplemental data and behavior to get the multi¬ 
document mechanism working right. 


In Project Builder: 

7 Add declarations of methods and 
instance variables to the 
ToDoDoc class. 

Select ToDoDoc.h in the project 
browser. 

Add the declarations at right. 

(Ellipses indicate existing 
declarations.) 


©interface ToDoDoc-.NSObject 
{ 

7* . . . */ 

NSMutableDictionary *activeDays; 

NSMutableArray *currentIterns; 

' } 

/* . .. */ 

- (NSMutableArray *)currentltems; 

- (void)setCurrentltems:(NSMutableArray *)newltems; 

- (NSMatrix *)itemMatrix; 

- (NSMatrix * ) markMatirix; 

- (NSMutableDictionary *)activeDays; 

- (void)saveDoc; 

- (id)initWithFile:(NSString *)aFile; 

- (void)dealloc; 

- (void)activateDoc; 

- (void)selectltem:(int)item; 

©end 

■ ■ ■ ' j 


The activeDays and currentltems instance variables hold the collection objects that 
store and organize the data of the application. (You’ll deal with these instance 
variables much more in the next section of this tutorial.) Many of the methods 
declared are accessor methods that set or return these instance variables or one 
of the matrices of the document. 

You’ll be switching between ToDoDoc.m and ToDoController.m in the next few tasks. 
The intent is not to confuse, but to show the close interaction between these 
two clashes. 
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8 Write the code that creates 
documents. 

Select ToDoController.m in the 
project browser. 

Implement ToDoController's 
newDoc: method. 


- (void)newDoc:(id)sender 
{ 

id currentDoc = [[ToDoDoc alloc] initWithFile:nil]; 

[currentDoc activateDoc]; 

> 

The newDoc: method is invoked when the user chooses New from the 
Document menu. The method allocates and initializes an instance of the 
document controller, ToDoDoc, thereby creating a document. (See the 
implementation of initWithFile: on the following page to see what happens in this 
process.) It then updates the document interface by invoking activateDoc.. 


Coordinate Systems in OpenStep 


The screen's coordinate system is the basis for all other 
coordinate systems used for positioning, sizing, drawing, and 
event handling. You can think of the entire screen as occupying 
the upper-right quadrant of a two-dimensional coordinate grid. 
The other three quadrants, which are invisible to users, take 
negative values along their x-axis, their y-axis, or both axes. The 
screen's quadrant has its origin in the lower left corner; the 
positive x-axis extends horizontally to the right and the positive y- 
axis extends vertically upward. A unit along either axis is 
expressed as a pixel. 

The screen coordinate system has just one function: to position 
windows on the screen. When your application creates a new 
window, it must specify the window’s initial size and location in 
screen coordinates.You can "hide" windows by specifying their 
origin points well within one of the invisible quadrants. This 
technique is often used in off-screen rendering in buffered 
windows. 


The reference coordinate system for a window is known as the 
base coordinate system. It differs from the screen coordinate 
system in only two ways: 

• It applies only to a particular window; each window has its own 
base coordinate system. 

* Its origin is at the lower left corner of the window, rather than 
the lower left corner of the screen. If the window moves, the 
origin and the entire coordinate system move with it 

For drawing, each NSView uses a coordinate system transformed 
from the base coordinate system or from the coordinate system of 
its superview. This coordinate system also has it origin point atthe 
lower-left corner of the NSView, making it more convenient for 
drawing operations. NSView has several methods for converting 
between base and local coordinate systems. When you draw, 
coordinates are expressed in the application's currentcoordmale 
system, the system reflecting the last coordinate transformations 
to have taken place within the current window. 
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A view's location is specified 
relative to the coordinate 
system of its window or 
superview. The coordinate 
origin for drawing begins at 
this point. 

The location of the window is 
expressed relative to the 
screen's origin, and its coord¬ 
inate system begins here too. 


The origins and dimensions of 
windows and panels are based 
on the screen origin. 
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SelectToDoDoc.minthe project 
browser. 

Implement ToDoDoc's 
initWithFile: method. 


- initWithFile:(NSString *)aFile 
{ 

NSEnumerator *dayenum; 

NSDate *itemDate; 

[super init]; 

if (aFile) { /* 1 */ 

activeDays = [NSUnarchiver unarchiveObjectWithFile:aFile]; 
if (activeDays) 

activeDays = [activeDays retain]; 

else 

NSRunAlertPanel(@"To Do", Couldn't unarchive file 
nil, nil, nil, aFile); 

} else { /* 2 */ 

activeDays = [[NSMutableDictionary alloc] init]; 

[self setCurrentltemsmil]; 

} 

if (![NSBundle loadNibNamed:©"ToDoDoc.nib" owner:self] ) /* 3 */ 

return nil; 

if (aFile) /* 4 */ 

[[itemMatrix window] setTitleWithRepresentedFilename:aFile]; 

else 

[[itemMatrix window] setTitle:@"UNTITLED"]; 

[[itemMatrix window] makeKeyAndOrderFront:self]; 
return self; 

} 

This method, which initializes and loads the document, has the following steps: 

1. Restores the document’s archived objects if the aFile argument is the pathname of 
a file containing the archived objects (that is, the document is opened). If objects 
are unarchived, it retains the activeDays dictionary; otherwise it displays an 
attention panel. 

2. Initializes the activeDays and currentltems instance variables. A aFile argument 
with a nil value indicates that the user is requesting a new document. 

3. Loads the nib file containing the document interface, specifying self as owner. 

4. Sets the title of the window; this is either the file name on the left of the title 
bar and the pathname on the right, or “UNTITLED” if the document is new. 

Before You Go On - 

Note the [itemMatrix window] message nested in the last message. Every object 
that inherits from NSView “knows” its window and will return that NS Window 
object if you send it a window message. 
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- (void)openDoc:(id)sender 
{ 

int result; 

NSString ^selected, *startDir; 

NSArray *fileTypes = [NSArray arrayWithObject:@"td"3; 

NSOpenPanel *oPanel = [NSOpenPanel openPanel]; /* 1 */ 

[oPanel setAllowsMultipleSelection:YES]; 

if ([[[NSApp keyWindow] delegate] isKindOfClass:[ToDoDoc class]]) 
startDir = [[[NSApp keyWindow] representedFilename] /* 2 */ 
stringByDeletingLastPathComponent]; 

else 

startDir = NSHomeDirectory(); 

result = DoPanel runModalForDirectory: startDir filernil /* 3 */ 
types:fileTypes]; 
if (result == NSOKButton) { 

NSArray *filesToOpen = [oPanel filenames]; 
int i/ count = [filesToOpen count]; 

for (i = 0 ; i<count; i++) { /* 4 */ 

NSString *aFile = [filesToOpen objectAtlndex:i]; 
id currentDoc = [[ToDoDoc alloc] initWithFile:aFile]; 
[currentDoc activateDoc]; 

> 

} 

> 

The openDoc: method displays the modal Open panel, gets the user’s response 
(which can be multiple selections) and opens the file (or files) selected. 

1. Creates or gets the NSOpenPanel instance (an instance shared among objects of 
an application). The previous message specifies the file types (that is, the 
extensions) of the files that will appear in the Open panel browser. The next 
message enables selection of multiple file in the panel’s browser. 

2. Sets the directory at which the NSOpenPanel starts displaying files either to 
the directory of any document window currently key or, if there is none, to 
the user’s home directory. 

3. Runs the NSOpenPanel and obtains the key clicked. 

4. If the key is NSOKButton, cycles through the selected files and, for each, 
creates a document by allocating and initializing a ToDoDoc instance, 
passing in a file name. 

The methods invoked by the Document menu’s Close and Save commands 
both simply send a message to another object. How they locate these objects 
exemplify important techniques using the core program framework. 


9 Implement the document¬ 
opening method. 

Select ToDoController.m in the 
project browser. 

Write the code for openDoc:. 
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10 Write the code that closes V ... - .... . 

. - (void)closeDoc:(id)sender 

documents. 

In ToDoController.m, implement [ [NSApp raai nwindow] performcioserself ] ; 

the closeDoc: method. } 

NSApp, the global NSApplication instance, keeps track of the application’s 
windows, including their status. Because only one window can have main status, 
the mainWindow message returns that NSWindow object— which is, of course, 
the one the user chose the Close command for. The closeDoc: method sends 
performClose: to that window to simulate a mouse click in the window’s close 
button. (See the following section, “Managing Documents Through 
Delegation,” to learn how the document handles this user event.) 



11 Write the code that saves 
documents. 

In ToDoController.m, implement 
the saveDoc: method. 


- (void)saveDoc:(id)sender 
{ 

id currentDoc = [[NSApp mainWindow] delegate]; 
if (currentDoc) 

[currentDoc saveDoc]; 

} 


As did closeDoc:, this method sends mainWindow to NSApp to get the main 
window, but then it sends delegate to the returned window to get its delegate, the 
ToDoDoc instance that is managing the document. It then sends the ToDoDoc- 
defined message saveDoc to this instance. 

Note: You could implement closeDoc: and saveDoc: in the ToDoDoc class, but the 
ToDoController approach was chosen to make the division of responsibility 
clearer. 
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Select ToDoDoc.m in the project 
browser. 

Implement the saveDoc: method. 


12 Implementthe accessor methods 
for ToDoControIler and ToDoDoc. 


- (void)saveDoc 
{ 

NSString *fn; 

if (![[[itemMatrix window] title] hasPrefix:@"UNTITLED"]) { 

fn = [[itemMatrix window] representedFilename]; /* 1 */ 

} else { 

int result; /* 2 */ 

NSSavePanel *sPanel = [NSSavePanel savePanel]; 

[sPanel setRequiredFileType:©"td"]; 
result = [sPanel runModalForDirectory:NSHomeDirectory() fileinil]; 
if (result == NSOKButton) { 
fn = [sPanel filename]; 

[[itemMatrix window] setTitleWithRepresentedFilename:fn]; 

} else 

return; 

} 

if (![NSArchiver archiveRootObject:activeDays toFile:fn]) /* 3 */ 
NSRunAlertPanel(©"To Do", ©"Couldn't archive file %@", 
nil, nil, nil, fn) ; 

else 

[[itemMatrix window] setDocumentEdited:NO]; 

} 


ToDoDoc’s saveDoc method complements ToDoController’s openDoc: method in 
that it runs the modal Save panel for users. 

1. The title method returns the text that appears in the window’s title bar. If the title 
doesn’t begin with “UNTITLED” (what new document windows are initialized 
with), then a file name and directory location has already been chosen, and is 
stored as the representedFilename. 

2. If the window tide begins with “UNTITLED” then the document needs to 
be saved under a user-specified file name and directory location. This part of 
the code creates or gets the shared NSSavePanel instance and sets the file 
type, which is the extension that’s automatically appended. Then it runs the 
Save panel, specifying the user’s home directory as the starting location. 

3. Archives the document under the chosen directory path and file name and, 
with the setDocumentEdited: message, changes the window’s close button to an 
“unbroken X” image (more on this in the next section). 

Don’t implement setCurrentltems: yet. This method does something special for 
the application that will be covered in “Managing the Data and Coordinating its 
Display (ToDoDoc)” on page 154. 
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Many classes of the Application Kit stand out in terms of relative 
importance. NSControl,for example, is the superclass of all user- 
interface devices, NSText underlies all text operations; and 
NSMenu has obvious significance. But four classes are at the 
core of a running application: NSResponder, NSApplication, 
NSWindow, and NSView. Each of these classes plays a critical 
role in the two primary activities of an application: drawing the 
user interface and responding to events. The structure of their 
interaction is sometimes called the core program framework. 


NSWindow 

An NSWindow object manages each physical window (that is, 
each window created by the Window Server) on the screen. It 
draws the title bar and window frame and responds to user 
actions that close, move, resize, and otherwise manipulate the 
window. 

The main purpose of an NSWindow is to display an application's 
user interface (or part of it) in its content area: that space below 
the title bar and within the window frame. A window's content is 
the NSViews it encloses, and at the root of this view hierarchy \s 
the content view, which fills the content area. Based on the 
location of a user event, NSWindows assigns an NSView in its 
content area to act as first responder. 

An NSWindow allows you to assign a custom object as its 
delegate and so participate in its activities. 



NSWindow 


NSApplication 


NSResponder 

■' . i?:' ' 

NSResponder is an abstract class, but it enables event handling 
in all classes that inherit from it. It defines the set of messages 
invoked when different mouse and keyboard events occur. It also 
defines the mechanics of event processing among objects in an 
application, especially the passing of events up the responder 
chainto each next responder until the event is handled. See the 
"Events and the Event Cycle" on page 163 for more on the 
responder chain and a description of first responder. 

NSApplication 

Every application must have one NSApplication object to act as 
its interface with the Window Server and to supervise and 
coordinate the overall behavior of the application. This object 
receives events from the Window Server and dispatches them to 
the appropriate NSWindows (which, in turn, distribute them to 
their NSViews). The NSApplication object manages its windows 
and detects and handles changes in their status as well as in its 
own status: hidden and unhidden, active and inactive. The 
NSApplication object is represented in each application by the 
global variable NSApp.To coordinate your own code with NSApp, 
you can assign your own custom object as its delegate. 

NSView 

Any object you see in a window's content area is an NSView. 
(Actually, since NSView is an abstract class, these objects are 
instances of NSView subclasses.) NSView objects are 
responsible for drawing and for responding to mouse and 
keyboard events. Each NSView owns a rectangular region 
associated with a particular window; it produces images within 
this region and responds to events occurring withinthe rectangle 

NSViews in a window are logically arranged in a view hierarchy, 
with the content view at the top of the hierarchy (see facing page 
for more information). An NSView references its window, its 
superview, and its subviews. It can be the first responder for 
events orthe next responder in the responder chain. An NSView's 
frame and bounds are rectangles that define its location on the 
screen, its dimension, and its coordinate system for drawing. 
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The View Hierarchy 

Just inside each window's content area—the area enclosed by 
the title bar and the other three sides of the frame—lies the 
content view. The content view is the root (or top) NSViewin the 
window's view hierarchy. Conceptually like a tree, one or more 
NSViews may branch from the content view, one one or more 
other NSViews may branch fromthese subordinate NSViews, and 
so on. Except for the content view, each NSView has one (and 
only one) NSView above it in the hierarchy. An NSView's 
subordinate views are called its subviews; its superior view is 
known as the superview. 

On the screen enclosure determines the relationship between 
superview and subview: a superview encloses its subviews. This 
relationship has several implications for drawing: 

• It permits construction of a superview simply by arrangement 
of subviews. (An NSBrowser is an instance of a compound 
NSView.) 

• Subviews are positioned in the coordinates of their superview, 
so when you move an NSView or transform its coordinate 
system, all subviews are moved and transformed in concert. 

• Because an NSView has its own coordinate system for 
drawing, its drawing instructions remain constant regardless 
of any change in position in itself or of its superview. 


Fitting Your Application In 

The core program framework provides ways for your application 
to access the participating objects and so to enter into the action. 

• The global variable NSApp identifiesthe NSApplication object. 
By sending the appropriate message to NSApp, you can obtain 
the application's NSWindow objects (windows), the key and 
main windows (keyWindow and mainWindow), the current 
event (currentEvent), the main menu (mainMenu), and the 
application's delegate (delegate). 

• Once you've identified an NSWindow object, you can get its 

c o nte nt vi e w (by se n d i n g it c ontentVie w) andfromthatyoucan 
get all subviews of the window. By sending messages to the 
NSWindow object you can also get the current event 
(currentEvent), the current first responder (firstResponder), 
and the delegate (delegate). 

• You can obtain from an NSView most objects it references. You 
can discover its window, its superview, and its subviews. 
Some NSView subclasses can also have delegates, which you 
can access with delegate. 

By making your custom objects delegates of the NSApplication 
object, your application's NSWindows, and NSViews that have 
delegates, you can integrate your application into the core 
program framework and participate in what's going on. 


NSApp 
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Managing Documents Through Delegation 

At certain points while an application is running you want to ensure that a 
document’s data is preserved or that a document’s edited status is tracked. 
These events occur when users: 

• Edit a document. 

• Close a window. 

• Quit the application. 

• Hide the application. 

• Switch to another application or window. 

Several classes of the Application Kit send messages to their delegates when 
these events occur, giving the delegate the opportunity to do the appropriate 
thing, whether that be saving a document to the file system or marking a 
document as edited. 

- (void)controlTextDidChange:(NSNotification *)notif 
{ 

[[itemMatrix window] setDocumentEdited:YES]; 

> 

When a control that contains editable text—such as a text field or a matrix of text 
fields—detects editing in a field, it posts the controlTextDidChange: notification 
which, like all notifications, is sent to the control’s delegate as well as to all 
observers. The setDocumentEdited: message causes the document’s window to 
change the image in its close button to a broken X. 

[window setDocumentEdited:NO] ; 

[window setDocumentEdited:YES]; 

Note: The ToDo object that, by notification, invokes the controlTextDidChange: 
method is itemMatrix, the matrix of to-do items (text fields). You will 
programmatically set ToDoDoc to be the delegate of this object later in this 
tutorial. 



1 Mark a document as edited. 

OpenToDoDoc.m. 

Implement the 

controlTextDidChange: method 
to mark the document. 
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2 Save edited documents when 
windows are closed. 

Implementthe delegation method 

windowShouldClose:. 


- (BOOL)windowShouldClose:(id)sender 
{ 

int result; 

/* 1 */ 

if (![[itemMatrix window] isDocumentEdited]) return YES; 

/* 2 */ 

[[itemMatrix window] makeFirstResponder:[itemMatrix window]]; 
result = NSRunAlertPanel(@"Close", ©"Document has been edited. 
Save changes before closing?", ©"Save", ©"Don't Save", 

©"Cancel"); 

/* 3 */ 

switch(result) { 

case NSAlertDefaultReturn: { 

[self saveDocItems]; 

[self saveDoc] ; 
return YES; 

} 

case NSAlertAlternateReturn: { 

return YES; 

} 

case NSAlertOtherReturn: { 

return NO; 

> 

} 

return NO; 


When users click a window’s close button, the window sends windowShouldClose: 
to its delegate. It expects a response directing it either to close the window or 
leave it open. 

1. Returns YES (meaning: go ahead, close the window) if the document hasn’t been 
edited. 

2. Makes the window its own first responder. This has the effect of forcing the 
validation of cells, flushing currently entered text to the method that handles 
it (more on this in the next section). 

3. Identifies the clicked button by evaluating the constant returned from 
NSRunAlertPanelO and returns the appropriate boolean value. If the user clicks 
the Save button, this method also updates internal storage with the currently 
displayed items (saveDocItems) and then sends saveDoc to itself to archive 
application data to a file. (saveDocItems is described in the following section.) 

Note: Do you recall the performCIose: method that ToDoController sends the 
document window when the user chooses the Close command? This method 
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simulates a mouse click on the window’s close button, causing windowShouldClose: 
to be invoked. 


3 Save edited documents when the 
user quits the application. 

In ToDoController.m, implement 
the delegation method 
applicationShouldTerminate:. 


- (BOOL)applicationShouldTerminate:(id)sender 
{ 

while ([NSApp keyWindow]) { 

int result; 

id doc = ([NSApp keyWindow] delegate]; 


if (![[NSApp keyWindow] isDocumentEdited]) { 

[[NSApp keyWindow] close]; 
if (doc) [doc autorelease]; 
continue; 

} 

if ([doc isKindOfClass:[ToDoDoc class]]) { 

NSString *repfile = [[NSApp keyWindow] representedFilename]; 
result - NSRunAlertPanel(©"To Do", @"Save %©?", ©"Save", 
©"Don't Save", ©"Cancel", 

([repfile isEqualToString:©""]?©"UNTITLED":repfile)); 
switch(result) { 

case NSAlertDefaultReturn: 


P 



[doc saveDocIterns]; 

(doc saveDoc]; 
break; 

, . • 

case NSAlertAlternateReturn: 

[[NSApp keyWindow] close]; 
break? 

case NSAlertOtherReturn: 


return NO; 

} 

if (doc) [doc autorelease]; 

} 

else 

[[NSApp keyWindow] close]; 

> 

return YES; 




NSApplication sends several message to its delegate. One of these messages— 
applicationShouldTerminate:— notifies the delegate that the application is about to 
terminate. The implementation of this method is similar to that for 
windowShouldClose:. What’s different is that this method cycles through all 
windows of the application and, if the window is managed by ToDoDoc, puts 
up an attention panel and responds according to the user’s choice. 
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Managing the Data and Coordinating its Display (ToDoDoc) 

If you recall the discussion on To Do’s design earlier in this chapter (“How To 
Do Stores and Accesses its Data” on page 119), you’ll remember that the 
application’s real data consists of instances of the model class, ToDoItem. To Do 
stores these objects in arrays and stores the arrays in a dictionary; it uses dates as 
the keys for accessing specific arrays. (Both the dictionary and its arrays are 
mutable, of course.) You might also recall that this design depends on a 
positional correspondence between the text fields of the document interface 
and the “slots” of the arrays. 

To lend clarity to this design’s implementation, this section follows the process 
from start to finish through which the ToDoDoc class handles entered data, and 
organizes, displays, and stores it. It also shows how the display and manipulation 
of data is driven by the selections made in the GalendarMatrix object. 

Start by revisiting a portion of code you wrote earlier for ToDoDoc’s initWithFile: 
method. 

- initWithFile:(NSString *)aFile 
{ 

/* . .. */ 
if (aFile) { 

activeDays = [NSUnarchiver unarchiveObjectWithFile:aFile]? 
if (activeDays) 

activeDays = [activeDays retain]; 

else 

NSRunAlertPanel(@"To Do", ©"Couldn't unarchive file %@", 
nil, nil, nil, aFile); 

} else { 

activeDays = [[NSMutableDictionary alloc] init]; 

[self setCurrentIterns:nil]; 

} 

/* ... */ 

} " 

Assume the user has chosen the New command from the Document menu. 
Since there is no archive file (aFile is nil), the activeDays dictionary is created but 
is left empty. Then initWithFile: invokes its own setCurrentltems: method, passing in 

nil. 
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1 Set the current items or f if 
necessary, create and prepare 
the array that holds them. 



(void)setCurrentltems:(NSMutableArray *)newltems 

-• •• j- . • '' • ' . k : " ■ . ^ • 

if (currentltems) [currentlterns autorelease]; 


Implement setCurrentltems:. 


if (newlterns) 

currentltems = [newltems mutableCopy]; 
else { 

int numRows = [[itemMatrix cells] count]; 
currentltems = [[NSMutableArray alloc] 
initWithCapacity:numRows]; 
while (--numRows >= 0) 

[currentltems addObject:"]; 

} 

} 


This “set” accessor method is like other such methods, except in how it handles 
a nil argument. In this case, nil signifies that the array does not exist, and so it 
must be created. Not only does setCurrentltems: create the array, but it “initializes” 
it with empty string objects. It does this because NSMutableArray’s methods 
cannot tolerate nil objects within the bounds of the array. 

So there’s now a currentltems array ready to accept ToDoItems. Imagine yourself 
using the application. What are the user events that cause a ToDoItem to be 
added to the currentltems array? To Do allows entry of items “on the fly,” and thus 
does not require the user to click a button to add a ToDoItem to the array. 
Specifically, items are added when users type something and then: 

• Press the Tab key. 

• Press the Enter key. 

• Click outside the text field. 

The controlTextDidEndEditing: delegation method makes these scenarios possible. 
The matrix of editable text fields (itemMatrix) invokes this method when the 
cursor leaves a text field that has been edited. 
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2 As items are entered in the 
interface, add ToDoltems to 
internal storage, delete them, or 
modify them, as appropriate. 

Implement 

controlTextDidEndEditing:. 


- (void)controlTextDidEndEditing:(NSNotification *)notif 

{ 

id curltem, newltem; 

int row = [itemMatrix selectedRow]; 

NSString *selName = [[itemMatrix selectedCell] stringValue]; 

/* 1 */ 

if (![[itemMatrix window] isDocumentEdited] || 

(row >= [currentltems count])) return; 
if (!currentltems) 

[self setCurrentltems:nil]; 

/* 2 */ 

if ( [selName isEqualToString : @" " ] && 

([[currentltems objectAtlndex:row] isKindOfClass: 

[ToDoItem class]]) && 

(![[[currentltems objectAtlndex:row] itemName] 
isEqualToString:" ] ) ) 

[currentltems replaceObjectAtlndex:row withObject:@""]; 

/* 3 */ 

else if ([[currentltems objectAtlndex:row] isKindOfClass: 
[ToDoItem class]] && 

(![[[currentltems objectAtlndex:row] itemName] 
isEqualToString:selName]) ) 

[[currentltems objectAtlndex:row] setltemName:selName]; 

/* 4 */ 

else if (![selName isEqualToString:"]) { 

newltem = [[ToDoItem alloc] initWithName:selName 
andDate:[calendar selectedDay]]; 

[currentltems replaceObjectAtlndex:row withObject:newltem]; 
[newltem release] ; 

} 

/* 5 */ 

[self updateMatrix]; 

} 


A control sends controlTextDidEndEditing: to its delegate when the cursor leaves a text 
field. In addition to creating new ToDoltems, this implementation of 
controlTextDidEndEditing: removes ToDoltems from arrays and modifies item text. 
What it does is appropriate to what the user does. 

1 . If the document hasn’t been edited (see controlTextDidChange:) or if the selected row 
exceeds the array bounds, it returns because there’s no reason to proceed. It 
initializes a currentltems array if one doesn’t exist. 

2. If the user deletes the text of an existing item, it removes the ToDoItem that 
positionally corresponds to the row of that deleted text. 

3. It changes the name of an item if the text entered in a field doesn’t match the 
name of the corresponding item in the currentltems array. 


155 



Chapter 4 


To Do Tutorial 


4. If either of the two previous conditions don’t apply, and text has been 
entered, it creates a new ToDoItem and inserts it in the currentltems array. 

5. Updates the list of items in the document interface. 


3 Update the document interface 
with the current items. 

implement updateMatrix:. 


(void)updateMatrix 


< 


ToDoItem *thisltem; 


in ( 


liillSS 


for {i—0; i<cnt / icrows; i++) { 

NSDate *due; 

thisltem = [currentltems objectAtlndex:i] 
if ([thisltem isKindOfClass:[ToDoItem class] 
if ( [thisltem secsUntilDue] ) 

due = [[thisltem day] addTimelnterval: 

[thisltem secsUntilDue]]; 

else 

due = nil; 

[[itemMatrix cellAtRow:i column:0] setStringValue: 

[thisltem itemName]]; 

[[markMatrix cellAtRowti column:0] 

[[markMatrix cellAtRow:i column:0] 

[thisltem itemStatus]]; 

f! I ; Ifillll :: .. . ^ V ? ' ' : 


/* 1 */ 





setTimeDue:due] , 
setTriState: 

k->- r 


else { 

[[itemMatrix cellAtRowii column:0] 
[[markMatrix cellAtRow:i column:0] 
[[markMatrix cellAtRow:i column:0] 


) 
y 


setStringValue: 
setTitle:"]? 
setlmage:nil]; 


) 



/* 2 */ 
@HH]; 

' 




The updateMatrix method writes the names of the items (ToDoItems) in the 
currentltems array to the text fields of itemMatrix. It also updates the visual 
appearance of the cells in the matrix (markMatrix) next to itemMatrix. These cells 
are instances of a custom subclass of NSButtonCell that you will create later in 
this tutorial. For now, just type all the code above; later, when you create the cell 
class, ToDoCell, you can refer back to this example to see what is happening. 

Basically, this method cycles through the array of items, doing the following: 

1. If an object in the array is a ToDoItem, it writes the item name to the text field 
corresponding to the array slot and updates the button cell next to the field. 

2. If an object isn’t a ToDoItem, it blanks the corresponding text field and cell. 
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4 Respond to user actions in the 
calendar. 

Implement CalendarMatrix's 
delegation methods. 


- (void)calendarMatrix:(CalendarMatrix *)matrix /* 1 */ 

didChangeToDate:{NSDate *)date 

{ 

[[itemMatrix window] makeFirstResponder:[itemMatrix window]]; 
[self saveDocItems]; 

[self setCurrentltems:[activeDays objectForKey:date]]; 

[dayLabel setStringValue:[date descriptionWithCalendarFormat: 

@"To Do on %a %B %d %Y" timeZone:[NSTimeZone defaultTimeZone] 
locale:nil]]; 

[self updateMatrix]; 

} 

- (void)calendarMatrix:(CalendarMatrix *)matrix /* 2 */ 

didChangeToMonth:(int)mo year:(int)yr 

{ 

[self saveDocItems]; 

[self setCurrentltems:nil]; 

[self updateMatrix]; 

} 

As you recall, CalendarMatrix declared two methods to allow delegates to “hook 
into” its behavior. Its delegate for this application is ToDoDoc. 

1. The calendar sends calendarMatrix:didChangeToDate: when users click a new day of 
the month. This implementation saves the current items to the activeDays 
dictionary. It then sets the current items to be those corresponding to the selected 
date (if there are no items for that date, the objectForKey: message returns nil and the 
currentltems array is initialized with empty strings). Finally it updates the matrix 
with the new data. 

2. The calendar sends calendarMatrix:didChangeTolVlonth:year: when users go to a new 
month and (possibly) a new year. This implementation responds by saving 
the current items to internal storage and presenting a blank list of items. 
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5 Save the data to internal storage. 
Implement saveDocItems:. 

6 Archive and unarchive the 
document's data. 

Implement encodeWithCoder: 
and initWithCoder:to archive and 
unarchive the dictionary holding 
the arrays of ToDoltems. 


- (void)saveDocItems 

{ 

ToDoItem *anltem; 

int i, cnt = [currentltems count]; 

// save day’s current items (array) to document dictionary 
for (i = 0 ; iccnt; i++) { 

if { (anltem = [currentltems objectAtlndex:i]) && 

([anltem isKindOfClass:[ToDoItem class]]) ) { 

[activeDays setObject:currentltems forKey: 

[anltem day]]; 
break; 

} 

> 

} 


This method inspects the currentltems array and, if it contains at least one 
ToDoItem, puts the array in the activeDays dictionary with a key corresponding 
to the date. 

Now that you’ve completed the methods for saving and archiving the collection 
objects holding ToDoltems, assume that the user has saved his document and 
then opens it. 
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7 Perform set-up tasks when the 
document's nib file is unarchived. 

Implement awakeFromNib as 
shown at right. 


- (void)awakeFromNib 
{ 

int i; 

NSDate *date; 

date = [calendar selectedDay]; 

[self setCurrentltems:[activeDays objectForKey:date]]; 
/* set up self as delegates */ 

[[itemMatrix window] setDelegate:self]; 

[itemMatrix setDelegate:self ] ; 

[[itemMatrix window] makeKeyAndOrderFront:self]; 

} 


When the ToDoDoc.nib file is completely unarchived, awakeFromNib is invoked. It 
sets the current items for today, sets a couple of delegates, and puts the 
document window in front of all other windows. 

Note: This method sets some delegates programmatically, which is redundant 
since you set these delegates in Interface Builder. However, this code 
demonstrates the programmatic route—and no harm done. 


8 Set up the document once it's 
created or opened. 

Implement activateDoc as shown 
at right. 


- (void)activateDoc 
{ 

if ([currentltems count]) [self updateMatrix]; 

[dayLabel setStringValue:[[calendar selectedDay] 

descriptionWithCalendarFormat:@ M To Do on %a %B %d %Y" 
timeZone:[NSTimeZone defaultTimeZone] locale:nil]]; 

} 


The activateDoc method is invoked right after a ToDo document is created or 
opened. It starts the ball rolling by updating the list matrices of the document 
and writing the current date to the “To Do on <date >” label. 
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Subclass Example: Overriding Behavior (SelectionNotifMatrix) 

You can often achieve significant gains in object behavior by making a subclass 
that adds only a small amount of code to its superclass. Such is the case with the 
subclass you’ll create in this section: SelectionNotifMatrix. 

The need for this class is this: An instance of NSMatrix is a control and thus can 
send action messages to its cell’s targets; but when it contains 
NSTextFieldCells, action messages are sent only when users press the Return 
key in a cell. You want the inspector to synchronize its displays when the user 
selects a new item by clicking a text field. To do this, you will override the 
method in NSMatrix that is invoked when users click the matrix; in your 
implementation, you’ll invoke the superclass method, detect the selected row, 
and then post a notification to interested observers. 


1 Create template source-code 
files and add to the project. 

Choose File ► New In Project. 

In the New File In ToDo panel, 
select the Class suitcase, turn on 
the Create header switch, and 
type "SelectionNotifMatrix" after 
Name. 

2 Add declarations to the header 
file. 


#import <AppKit/AppKit.h> 

extern NSString *SelectionInMatrixNotification =/*!*/ 
SelectionlnMatrixNotification”; 

©interface SelectionNotifMatrix : NSMatrix 
{ 

> 

- (void)raouseDown:(NSEvent *)theEvent; /* 2 */ 

©end 


1. Declares a string constant identifying the notification that will be posted. 

2. Declares mouseDown:, the method implemented by the superclass that 
SelectionNotifMatrix overrides. 


3 Override mouseDown: 

In SelectionNotifMatrix.m, 
implement mouseDown: as 
shown here. 


- (void)mouseDown:(NSEvent *)theEvent 
int row; 

[super mouseDown:theEvent]; 

row = [self selectedRow]; 
if (row != -1) { 

[[NSNotificationCenter defaultCenter] 

postNotificationName:@"SelectionlnMatrixNotification" 
object:self userlnfo:[NSDictionary dictionaryWithObjectsAndKeys: 
[NSNumber numberWithlnt:row], @"Itemlndex”, nil]]; 

} 

} 


SI ■ ' 




/* 1 */ 
/* 2 */ 
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This override of mouseDown: does the following: 

1. Invokes NSMatrix’s implementation of mouseDown: to allow the normal 
processing of this event. 

2. Gets the row of the cell clicked and, if it’s a valid row, creates a userlnfo 
dictionary containing the clicked row, and posts the 
SelectionlnMatrixNotification. 

Now that you’ve created the SelectionNotifMatrix class, you must re-assign the 
class membership of the object in the interface. You can do this easily in 
Interface Builder. 


4 Replace the class of the matrix 
object. 

In Interface Builder: 

OpenToDoDoc.nib. 

Select the matrix of editable text 
cells. 

Open the inspector and choose 
Custom Class from the pop-up 
menu. 

Select SelectionNotifMatrix in 
the browser of compatible 
classes. 


SelectionNotifMatrix Inspector X 


‘Custom Class 


Q ass 


[Calendar Matrix 


SelectionNotifMatrix 



The Custom Classes browser lists the original 
class of the selected object and all compatible 
custom subclasses. 
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You can depict the interaction between a user and an OpenStep 
application as a cyclical process, with the Window Server playing 
an intermediary role (see illustration below). This cycle—-the 
event cycle —usually starts at launch time when the application 
(which includes all the OpenStep frameworks it's linked to) sends 
a stream of PostScript code to the Window Server to have it draw 
the application interface. 

Then the application begins its main event loop and begins 
accepting inputfromthe user (seefacing page). When users click 
or drag the mouse or type on the keyboard, the Window Server 
detects these actions and processes them, passing them to the 
application as events. Often the application, in response to these 
events, returns another stream of PostScript code to the Window 
Server to have it redraw the interface. 

In addition to events, applications can respond to other kinds of 
input, particularly timers, data received at a port, and data waiting 
at a file descriptor. But events are the most important kind of input. 


codes identifying characters and keys, and various other kinds of 
information. 

An NSEvent also divulges the type of event it represents. There 
aremanyeventtypes(NSEve ntTyp e); th ey f a 11 i nto f i ve c ate g o r i e s: 

• Keyboard events Generated when a key is pressed down, a 
pressed key is released, or a modifier key changes. Of these, 
key-down events are the most useful. When you handle a key- 
down event, you often determine the character or characters 
associated with the event by sending the NSEvent a 
characters message. 

• Mouse events Mouse events are generated by changes in 
the state of the mouse buttons (that is, down and up) for both 
left and right mouse buttons and during mouse dragging. 
Events are also generated when the mouse simply moves, 
without any button pressed. 


Events 

The Window Server treats each user action as an event; it 
associates the event with a window and reports it to the 
application that created the window. Events are objects: 
instances of NSEvent composed from information derived from 
the user action. 

All eventmethods defined in NSResponder (such as mouseDown: 
and keyDown:) take an NSEvent as their argument. You can query 
an NSEvent to discover its window, the location of the event 
within the window, and the time the event occurred (relative to 
system start-up). You can also find out which (if any) modifier keys 
were pressed (such as Command, Alternate, and Control), the 


• Tracking-rectangle events If the application has asked the 
window system to set a tracking rectangle in a window, the 
window system creates mouse-entered and mouse-exit 
events when the cursor enters the rectangle or leaves it 

• Periodic events A periodic event notifies an application that 
a certain time interval has elapsed. An application can request 
that periodic events be placed in its event queue at a certain 
frequency. They are usually used during a tracking loop. (These 
events aren't passed to an NSWindow.) 

• Cursor-update events An cursor-update event is generated 
when the cursor has crossed the boundary of a predefined 
rectangular area. 
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The Event Queue and Event Dispatching First Responder and the Responder Chain 


When an application starts up, the NSApplication object (NSApp) 
starts the main event loop and begins receiving events from the 
Window Server (see page 116). As NSEvents arrive, they're putin 
the event queuemthe order they're received. On each cycle of 
the loop, NSApp gets the topmost event, analyzes it, and sends an 
event message to the appropriate object. (Event messages are 
defined by NSResponder and correspond to particular events.) 
When NSApp finishes processing the event, it gets the next event, 
and repeats the process again and again until the application 
terminates. 

The object that is "appropriate" for an event depends on the type 
of event. NSApp sends most event messages to the NSWindow in 
which the user action occurred. If the event is a keyboard or 
mouse event, the NSWindow forwards the message to one of the 
objects in its view hierarchy: the NSView within which the mouse 
was clicked or the key was pressed. If the NSView can respond 
to the event—that is, it accepts first responder status and defines 
an NSResponder method corresponding to the event message— 
it handles the event 
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If the NSView cannot handle an event, itforwardsthe message to 
the next responder in the responder chain (see below). It travels 
up the responder chain until an object handles it. 

NSWindow handles some events itself, and doesn'tforward them 
to an NSView, such as window-moved, window-resized, and 
window-exposed events. (Sincethese are handled by NSWindow 
itself, they are not defined in NSResponder.) NSApp also 
processes a few kinds of events itself; these include cursor- 
update, and application-activate and -deactivate events. 


Each NSWindow in an application keeps track of the object in its 
view hierarchy that has first responderstatus. This is the NSView 
that currently receives keyboard events for the window. By 
default, an NSWindow is its own first responder, but any NSView 
within the window can become first responder when the user 
clicks it with the mouse. 

You can also set the first responder programmatically with the 
NSWindow's makeFirstResponder: method. Moreover, the first- 
responder object can be a target of an action message sent by an 
NSControl,such as a button ora matrix. Programmatically,you do 
this by sending setTarget: to the NSControl (or its cell) with an 
argument of nil. You can dothe same thing in Interface Builder by 
making a target/action connection between the NSControl and 
the First Responder icon in the Instances display of the nib file 
window. 

Recall that all NSViews of the application, as well as all 
NSWindows and the application object itself, inherit from 
NSResponder, which defines the default message-handling 
behavior: events are passed up the responder chain. Many 
Application Kit objects, of course, override this behavior, so 
events are passed up the chain until they reach an object that 
does respond. 

The series of next responders in the responder chain is 
determined by the interrelationships between the application's 
NSView, NSWindow, and NSApplication objects (see page 149). 
For an NSView, the next responder is usually its superview; the 
content view's next responder is the NSWindow. From there, the 
event is passed to the NSApplication object 

For action messages sent to the first responder, the trail back 
through possible respondents is even more detailed. The 
messages are first passed up the responder chain to the 
NSWindow and then to the NSWindow's delegate. Then, if the 
previous sequence occurred in the key window the same path is 
followed for the main window. Then the NSApplication object 
tries to respond, and failing that, it goes to NSApp's delegate. 
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Creating and Managing an Inspector (ToDolnspector) 


An inspector is a panel of fields and controls that enable users to examine and 
set an object’s attributes. Because objects often have many attributes and 
because you want to make it easy for users to set those attributes, inspectors 
usually have more than one display; users typically access these multiple 
displays using a pop-up list. 

The ToDo application has an inspector panel that allows users to inspect and set 
the attributes of the currently selected ToDoItem. The inspector panel has its 
own controller: ToDolnspector. While showing you how to create the inspector 
panel and ToDolnspector, this section focuses on four things: 

• Managing displays according to user selections 

• Getting the current ToDoItem 

• Updating the currently selected display 

• Updating the current ToDoItem as users make changes to it 


In Interface Builder 

1 Create a new nib file named 
ToDolnspector.nib and add it to 
the ToDo project. 

2 Create the inspector panel. 

Drag a panel object from the 
Windows palette. 

Make the title of the panel 
"Inspector." 

Resize the panel, using the 
example at right as a guide. 

Put labels and fields on the panel 
and set their attributes (as 
shown). 

Put a pop-up button on the panel 
and set cell titles (as shown). 

Assign tags to the pop-up button 
cells. 

Create a separator line just below 
the pop-up button. 

Put an empty box object in the 
lower part of the panel. 
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The text fields after the labels should have a light 
gray background and should not be editable. The 
lower of these fields should be large enough to 
hold the text of an item. 


Double-click to display the three default cells 
(Item 1, Item2, and Item3). Then, for each cell, 
double-click its title to select it and type the new 
title. Assign tags (0 to 2) to the cells. 


Turn off the title attribute and resize the box object 
so it fits just inside the lower part of the panel. 
To provide a guide for resizing, this example 
shows the box having a border; turn the border 
off after resizing. 


Before You Go On -- 

You might be wondering about the empty box object in the lower part of the 
panel. This box by itself may not seem a promising thing for displaying object 
attributes, but it is critical to the workings of the inspector panel. A box that you 
drag from the Views palette contains one subview, called the content view. 
NSBox’s content view fits entirely within the bounds of the box. NSBox 
provides methods for obtaining and changing the content view of boxes. You’ll 
use these methods to change what the inspector panel displays. 
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3 Create an off-screen panel 
holding the inspector's displays. 

Drag a panel object from the 
Windows palette. 

Resize the panel, using the 
example at right as a guide. 

Put the labels, text fields, scroll 
view, and switch and radio-button 
matrices on the panel shown in 
the example at right. 

Make the When to Reschedule 
and When to Notify groupings 
(boxes). 

Make three other groupings for 
the three displays: Notes, 
Reschedule, and Notification. 

Resize the resulting boxes to the 
same dimensions as the 
"dummy" view in the inspector 
panel. 


Creating and Managing an Inspector (ToDolnspector) 


The scroll view is its own grouping (Notes). 
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Turn off the border attributes of each outer box. 


Before You Go On - 

You probably now see where the inspector panel gets its displays and how it puts 
them in place. When the inspector panel is first opened (and ToDolnspector.nib is 
loaded) the inspector controller, ToDolnspector, replaces the content view of 
the inspector’s empty box (dummyView) with the content view of the Notification 
box in the off-screen panel. Thereafter, every time the user chooses a new pop¬ 
up button in the inspector panel, ToDolnspector replaces the currently 
displayed content view with the content view of the associated off-screen box. 
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4 Define the ToDolnspector class. 

Create a subclass of NSObject 
and name it "ToDolnspector." 

Add the outlets and actions in the 
tables at right to the new class. 

Instantiate ToDolnspector. 

Connect the ToDolnspector 
object to its outlets and as the 
target of action messages (see 
tables at right). 

Connect ToDolnspector and the 
inspector panel via the panel's 
delegate outlet. 

Close both panels. 

Save ToDolnspector.nib. 

Create source-code files for 
ToDolnspector and add them to 
the project. 


Outlet 

Connection From ToDolnspector To... 

dummy View 

The empty box object in the inspector panel 

inspectorViews 

The title bar of the off-screen panel 

notesView 

The box in the off-screen panel containing the scroll view 

notifView 

The box in the off-screen panel containing the fields and controls 
related to notification of impending items 

reschedView 

The box in the off-screen panel containing the fields and controls 
related to rescheduling items 

inspPopUp 

The pop-up button on the inspector panel 

inspDate 

The uneditable text field next to the "Date" label 

inspltem 

The uneditable text field next to the "Item" label 

inspNotifHour 

The first field after the "Time" label 

inspNotif Minute 

The second field after the "Time" label 

inspNotifAMPM 

The matrix holding the "AM" and "PM" radio buttons 

inspNotifOtherHours 

The text field in the "When to Notify" box 

inspNotifSwitch Matrix 

The matrix of switches in the "When to Notify" box 

inspSchedComplete 

The "Task Completed" switch 

inspSchedDate 

The text field in the "When to Reschedule" box 

inspSched Matrix 

The matrix of switches in the "When to Reschedule" box 

inspNotes 

The text object inside the scroll view 

Action 

Connection To ToDolnspector From... 

newInspectorView: 

The pop-up button on the inspector panel 

switchChecked: 

The matrix of switches in the "When to Notify" box, the AM-PM matrix, 
the "Task Completed" switch, and the matrix of switches in the "When 
to Reschedule" switches. 
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In Project Builder 

5 Add declarations to 
ToDolnspector.h. 

Open ToDolnspector.h. 

Type the declarations shown at 
right (ellipses indicate existing 
declarations). 

Import ToDoltem.h and 
ToDoDoc.h. 


©interface ToDolnspector : NSObject 
{ 

ToDoItem *currentltem; 

/* ... */ 

} 

/* ... */ 

- (void)setCurrentltem:(ToDoItem *)newltem; 

- (ToDoItem *)currentltem; 

- (void)updatelnspector:(ToDoItem *)item; 
©end 


The ToDolnspector class has a utility function for clearing switches set in a 
matrix and defines constants for the tags assigned to the pop-up buttons. 


Open ToDolnspector.m. 

Forward-declare 
clearButtonIVIatrixO at the 
beginning of the file. 

Define enum constants for the 
pop-up button tags. 


static void clearButtonMatrix(id matrix); 
enum { notifTag - 0, reschedTag, notesTag }; 


Using tags to identify cells rather than cell titles is a better localization strategy. 

ToDolnspector has two accessor methods, one that gives out the current item 
and one that sets the current item. 


6 Implement the accessor methods 
for the class. 

Implement currentltem to return 
the instance variables it names. 

Implement setCurrentltem: as 
shown at right. 


- (void)setCurrentltem:(ToDoItem *)newltem 
{ 

if (currentltem) [currentltem autorelease]; 
if (newltem) 

currentltem = [newltem retain]; 

else 

currentltem - nil; 

[self updatelnspector:currentltem]; 


/* 1 */ 

/* 2 */ 


This implementation of a “set” accessor method probably seems familiar to 
you—except for a couple of things: 

1. Instead of copying the new value, this implementation retains it. By retaining, it 
shares the current ToDoItem with the document controller (ToDoDoc) that has 
sent the setCurrentltem: message, enabling both objects to update the same 
ToDoItem simultaneously. 

Note: Later in this section, you’ll invoke ToDoInspector’s setCurrentltem: 
method in various places in ToDoDoc.m. 

2. Updates the current display of the inspector with the appropriate values of 
the new ToDoItem. 
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7 Switch inspector displays based 
on user selections. 

Implement newInspectorView:. 


- (void)newInspectorView:(id)sender 
{ 

NSBox *newView=nil; 

NSView *cView = [[inspPopUp window] contentView]; /* 1 */ 

int selected = [[inspPopUp selectedltem] tag]; 

switch(selected){ /* 2 */ 

case notifTag: 

newView = notifView; 
break; 

case reschedTag: 

newView = reschedView; 
break; 

case notesTag: 

newView = notesView; 

" } 

if ([[cView subviews] containsObject:newView]) return; /* 3 */ 
[dummyView setContentView:newView]; /* 4 */ 

if (newView == notifView) [inspNotifHour selectText:self]; 
if (newView == notesView) [inspNotes 

setSelectedRange:NSMakeRange(0,0)]; 

[self updatelnspector:currentltem]; /* 5 */ 

[cView display]; 

} 


This method switches the current inspector display according to the pop-up 

button users select; it does this switching by replacing the dummyView’s content 

view. Toward this end, the method: 

1. Gets the panel’s content view and the tag of the selected pop-up button. 

2. Assigns to the newView local variable the off-screen box object corresponding 
to the tag of the selected pop-up button. 

3. Returns if the selected display is already on the inspector panel. The subviews 
message returns an array of all subviews of the inspector panel’s control view, 
and the containsObject: message determines if the chosen display is among 
these subviews. 

4. Replaces the content view of the inspector panel’s dummyView. In awakeFromNib 
(which you’ll soon implement) you’ll retain each original content view. The 
setContentView: method replaces the new view and releases the old one; 
because it’s been retained, the replaced view doesn’t disappear. 

5. Updates the inspector with the current item; this item hasn’t changed, but the 
display is new and so the set of instance variables to be displayed is different. 
The display message forces a re-draw of the inspector panel’s views. 
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8 Update the current inspector 
display with the new ToDoltem. 

Write the first part of the 
updatelnspector: method shown 
at right. 


(void)updatelnspector:(ToDoltem *)newltem 


{ 


: 


int minute=0 / hour=0, selected=0; 

selected = [[inspPopUp selectedltem] tag]; /* 1 */ 

[[inspPopUp window] orderFront:self]; 

if (newltem && [newltem isKindOfClass:[ToDoltem class]]) { /* 2 */ 
[inspltem setStringValue:[newltem itemName]3; 

[inspDate setStringValue:[[newltem day] 

descriptionWithCalendarFormat:@"%a, %b %d %Y" 
timeZone:[NSTimeZone localTimeZone] localernil]]; 
switch(selected) { 

case notifTag: { /* 3 */ 

long notifSecs, dueSecs = [newltem secsUntilDue]; 

BOOL ampm = ConvertSecondsToTime(dueSecs, &hour, kminute 
[[inspNotifAMPM cellAtRowrO column:0] setstate:!ampm]; 

[ [inspNotif AMPM cellAtRowrO column-.l] sets tate : ampm] ; 

[inspNotifHour setlntValue:hour]; 

[inspNotifMinute setlntValueiminute]; 
notifSecs = dueSecs - [newltem secsUntilNotif]; 
if (notifSecs == dueSecs) notifSecs = 0; 
clearButtonMatrix(inspNotifSwitchMatrix); 
switch(notifSecs) { /* 4 */ 

case 0: 

[ [inspNotifSwitchMatrix cellAtRow:0 column:0] 

setState-.YES] ; 
break; 

case (hrInSecs/4): 

[[inspNotifSwitchMatrix cellAtRow:l column:0] 
setState:YES]; 
break; 

case (hrlnSecs): 

[[inspNotifSwitchMatrix cellAtRow:2 column:0] 
setState:YES]; 
break; 

case (daylnSecs): 

[[inspNotifSwitchMatrix cellAtRow:3 column:0] 
setState:YES]; 
break; 

default: /* Other */ 

[[inspNotifSwitchMatrix cellAtRow:4 column:0] 
setState:YES]; 

[inspNotifOtherHours setlntValue: 

((dueSecs-notifSecs)/hrlnSecs)]; 
break; 


w w 



} 

break; 

} 

case reschedTag: 
break; 
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The updatelnspector: method is a long one, so we’ll approach it in stages. This first part update 
the common data elements (item name and date) and, if the selected display is for notification 
updates that display. 

1. Gets the tag assigned to the selected pop-up button. 

2. Tests the argument newltem to see if it is a ToDoItem. This test is important 
because if the argument is nil, the method clears the display of existing data 
(next example). 

If newltem is a ToDoItem, updatelnspector: first updates the Item and Date 
fields. 

3. If the tag of the selected pop-up button is notifTag, updates the associated 
inspector display. This task starts by converting the due time from seconds to 
hour, minute, and PM boolean values and then setting the appropriate fields 
and button matrix with these values. 

4. Sets the appropriate switch in the “When to Notify” matrix. It starts with the 
difference (in seconds) between the time the item is due and the time the 
item notification is sent. It calls clearButtonMatrixO to turn all switches off and 
then, in a switch statement, sets the switch corresponding to the difference in 
value between seconds from midnight before due and before notification. 

Before You Go On - 

Update the Notes display: Add code to update the inspector’s Notes display from the 
information in the ToDoItem passed into updatelnspector:. (Check the 
documentation on NSText to see what method is suitable for this.) The selected 
pop-up button must have notesTag assigned to it. Also put the cursor at the start 
of the text object by selecting a “null” range. 

Note that tutorial omits the rescheduling logic of the ToDo application, 
including the code in this method that would update the “Reschedule” display. 
Rescheduling of ToDoItems is reserved as an optional exercise for you at the 
end of this tutorial. 
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Finish the implementation of 
updatelnspector: by resetting all 
displays if the argument is nil. 


Implement the 
clearButtonMatrixf) utility 
function. 


} 

else if (Inewltem) { /* newltem is nil */ 

[inspltem setStringValue:@""]; 

[inspDate setStringValue:@; 

[inspNotifHour setStringValue:@""]; 

[inspNotifMinute setStringValue:@""]? 

[[inspNotifAMPM cellAtRowrO column:0] setState:YES]; 

[[inspNotifAMPM cellAtRowrO column:l] setState:NO]; 
clearButtonMatrix(inspNotifSwitchMatrix); 

[[inspNotifSwitchMatrix cellAtRowrO column:0] 
setState:YES]; 

[inspNotifOtherHours setStringValue:@""]; 

[inspNotes setstring:"]; 

} 

} 

As you’ve most likely noticed, the updatelnspector: method calls the function 
clearButtonMatrixO, which resets the states of all button cells in a switch matrix to 
NO. This function has a counterpart, indexOfSetCelll), that returns the index of the 
currently selected switch. 


void clearButtonMatrix(id matrix) 

{ 

int i, cnt=[[matrix cells] count]; 
for(i=0; i<cnt; i++) 

[[matrix cellAtRowri column:0] setState:NO]; 

} 

The cells message returns the cells of the matrix as an array; the count message 
determines the number of cells. 


171 



Chapter 4 


To Do Tutorial 


9 


Update the current item with new 
values entered in the inspector. 

Implement switchChecked: to 
apply changes made through 
switches and other controls. 


- (void)switchChecked:(id)sender 

^ . M: 

long tmpSecs=0; 




: 
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int idx = 0; 

id doc = [[NSApp mainWindow] delegate]; 
if (sender == inspNotifAMPM) { 

if ((inspNotifHour intValue]) { 

tmpSecs = ConvertTimeToSeconds([inspNotifHour intValue], 
[inspNotifMinute intValue], 

[[sender cellAtRow:0.column:1] state]); 

[currentItem setSecsUntilDue:tmpSecs]; 

[[NSApp mainWindow] setDocumentEdited:YES]; 

[doc updateMatrix]; 

} 

} else if (sender == inspNotifSwitchMatrix) { 
idx = [inspNotifSwitchMatrix selectedRow]; 
tmpSecs = [currentltem secsUntilDue]; 
switch(idx) { 
case 0: 

[currentltem setSecsUntilNotif:0]; 
break; 
case 1: 

[currentltem setSecsUntilNotif:tmpSecs-(hrInSecs/4) 
break; 
case 2: 

[currentltem setSecsUntilNotif:tmpSecs-hrlnSecs]? 
break; 
case 3: 

[currentltem setSecsUntilNotif:tmpSecs-daylnSecs]; 
break; 

case 4: // Other 

[currentltem setSecsUntilNotif:([inspNotifOtherHours intValu 
* hrlnSecs)]; 
break; 
default: 

NSLog(@"Error in selectedRow”); 
break; 

} 

[[NSApp mainWindow] setDocumentEdited:YES]; 

} else if (sender == inspSchedComplete) { 

[currentltem setltemStatus:complete]; 

[[NSApp mainWindow] setDocumentEdited:YES]j 

[doc updateMatrix]; 

. : : 
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} else if (sender == inspSchedMatrix) { 
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When users click a switch button on any inspector display, or when they click 
one of the AM-PM radio buttons, the switchChecked: method is invoked. This 
method works by evaluating the sender argument: the sending object. 

1. If sender is the radio-button matrix (AM-PM), gets the new time due by calling the 
utility function ConvertTimeToSecondsO, sets the current item to have this new value, 
marks the document as edited, and then sends updateMatrix to the document 
controller to have it display this new time. 

2. If sender is the “When to Notify’’ matrix, gets the index of the selected cell 
and the seconds until the item is due. It evaluates the first value in a switch 
statement and uses the second value to set the current item’s new secsUntilNotif 
value. It also sets the window to indicate an edited document. 

3. If sender is the “Task Completed” switch, sets the status of the current item 
to “complete,” sets the window to indicate an edited document, and has the 
document controller update its matrices. 

4. As before, implementation of this rescheduling block is left as a final exercise. 

Since text fields are controls that send target/action messages, you could also 
have switchChecked: respond when data is entered in the fields. However, users 
might not press Return in a text field so you can’t assume the action message will 
be sent. Therefore, it’s better to rely upon delegation messages. 
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Update the current item if 
changes are made to the 
contents of text fields or the text 
object of the inspector panel. 


- (void)textDidEndEditing:(NSNotification *)notif /* 1 */ 

{ 

if ([notif object] = = inspNotes) 

[currentltem setNotes:[inspNotes string]]; 

[[NSApp mainWindow] setDocumentEdited:YES]; 

} 

- (void)controlTextDidEndEditing:(NSNotification *)notif 

{ 

long tmpSecs=0; 

if ([notif object] == inspNotifHour II /* 2 */ 

[notif object] == inspNotifMinute) { 

tmpSecs. = ConvertTimeToSeconds([inspNotifHour intValue], 
[inspNotifMinute intValue], 

[[inspNotifAMPM cellAtRow:0 column:l] state]); 
[currentltem setSecsUntilDue:tmpSecs]; 

[[[NSApp mainWindow] delegate] updateMatrix]; 

[[NSApp mainWindow] setDocumentEdited:YES]; 

} else if ([notif object] == inspNotifOtherHours) { /* 3 */ 

if ([inspNotifSwitchMatrix selectedRow] ' == 4) { 

[currentltem setSecsUntilNotif:([inspNotifOtherHours 
intValue] * hrlnSecs)]; 

[[NSApp mainWindow] setDocumentEdited:YES]; 

} 

} else if ([notif object] == inspSchedDate) { /* 4 */ 

} 

} 


The textDidEndEditing: and controlTextDidEndEditing: notification messages are sent to 
the delegate (and all other observers) when the cursor leaves a text object or text 
field (respectively) after editing has occurred. 

1. After editing takes place in the “Notes” text object, this method is invoked, and it 
responds by resetting the notes instance variable of the ToDoItem with the 
contents of the text object. 

2. If the object behind the notification is the hour or minute field of the 
“Notifications” display, controlTextDidEndEditing: computes the new due time, 
sets the current item to have this new value, and then sends updateMatrix to the 
document controller to have it display this new time. (This code is almost the 
same as that for the AM-PM matrix in the switchChecked: method.) 
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10 Synchronize the items displayed 
in the document with the 
inspector. 

OpenToDoDoc.m. 

Import ToDolnspector.h. 

Add the code at righttothe end of 

the controlTextDidEndEditing: 

method. 

Post identical notifications in the 
otherToDoDoc methods listed in 
the table below. 

In ToDoDoc.h declare as extern 
the string constant 
ToDoltemChangedNotification. 

In ToDoDoc.m, declare and 
initialize the same constant. 


3. If the object behind the notification is the “Other...hours” text field in the 
“When to Notify” box, the method verifies that the “Other” switch is 
checked and, if it is, sets the ToDoItem with the new value. 

4. Here is another empty rescheduling block of code that you can fill out in a 
later exercise. 

Now it’s time to address two related problems in synchronizing displays of data. 
The first is the requirement for the inspector to display the ToDoItem currently 
selected in the document. In ToDoDoc.m write code that communicates this object 
to ToDolnspector through notification. 

id curltem; 

/* ... */ 

if (curltem - [currentltems objectAtIndex:row]) { 
if (![curltem isKindOfClass:[ToDoItem class]]) 
curltem = nil; 

[[NSNotificationCenter defaultCenter] postNotificationName: 
ToDoltemChangedNotification object:curltem 
userlnfo:nil]; 

} 


The controlTextDidEndEditing: method is where ToDoItems are added, removed, or 
modified, so it’s especially important here to let ToDolnspector know when 
there’s a change in the current ToDoItem. The fragment of code above gets the 
current item (row holds the index of the selected row); if the returned object isn’t 
a ToDoItem, curltem is set to nil. Then the code posts a 

ToDoltemChangedNotification, passing in curltem as the object related to the 
notification. 

Post an identical notification in otherToDoDoc methods that select a 
ToDoItem 0 r that require the removal of the currently displayed ToDoItem 
from the inspector’s display. In methods of this second type, there is no need to 
get the current item because the object argument of the notification should 
always be nil. This argument is eventually passed to ToDoInspector’s 
updatelnspector:, to which nil means “clear the display.” 


Other Methods Posting Notifications to ToDolnspector 

object: Argument 

calendarMatrix:didChangeToDate: 

nil 

calendarMatrix:didChangeToMonth:year: 

nil 

windowShouldClose: (for both "Save" and "Close") 

nil 

selectionlnMatrix: 

current item or nil 
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11 Open the inspector panel when 
users choose the Inspector 
command. 

Implement ToDoController's 
showlnspector: method to load 
ToDolnspector.nib and make the 
inspector panel the key window. 

12 Update the document and 
inspector to display initial 
values. 

In ToDoDoc.m, implement 
selectltem:. 

Invoke this method at the 
appropriate places (see below). 


The use of notifications to 
communicate changes in one 
object to another object in an 
application is a good design 
strategy because it removes the 
need for the objects to have 
specific knowledge of each other. 
It also makes the application 
more extensible, because any 
number of objects can also 
become observers of the changes. 
However, there is a way for 
ToDoDoc to locate 
ToDoInspector reliably using the 
various relationships established 
within the program framework. 
See page 189 to see how this is 
done. 


The second data-synchronization problem involves the selection and display of 
initial values in the document and the inspector when the user: 

• Opens the inspector 

• Opens a document 

• Selects a new day from the calendar 

You must return to ToDoDoc.m to write code that implements this behavior. 

- (void)selectltem:(int)item 
; { 

id thisItem = [currentltems objectAtIndex:item]; 

[itemMatrix selectCellAtRow:item column:0]; 
if (thisltem) { 

if (1[thisltem isKindOfClass:[ToDoItem class]]) thisltem = nil; 
[[NSNotificationCenter defaultCenter] 

pos tNotificationName:ToDolt emChangedNotification 
object:thisltem 
userInfo:nil]; 

} 

> 

The selectltem: method selects the text field identified in the argument and posts 
a notification to the inspector with the associated ToDoItem as argument (or nil 
if the text field is empty). Next, invoke selectltem: in these methods: 


Method 

Comment 

calendarMatrix:didChangeToDate: Make it the final message, with an argument of 0 (ToDoDoc.m). 

openDoc: 

Invoke after opening a document, with an argument of 0 

(ToDoController.m) 

showlnspector: 

Invoke afer opening the inspector panel, passing in the index of the 
selected row in the document. (ToDoController.m). Hint: Get the 
current document by querying for the delegate of the main window, 
then obtain the selected row from this object. 


Before You Go On - 

Make ToDoInspector respond to the notification. Declare a notification method 
named currentltemChanged: and implement it to set the current item with the object 
value of the notification. Then, in init or awakeFromNib, add ToDoInspector as an 
observer of the ToDoItemChangedNotification, identifying currentltemChanged: 
as the method to be invoked. 
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13 Format and validate the contents 
of inspector text fields. 

In ToDolnspector.m: 

Implement awakeFromNib as 
shown at right. 

Implement controhisValidObject: 
to ensure that users can only 
enter the proper range of 
numbers in the hour and minute 
text fields. 


- (void)awakeFromNib 
{ 

NSDateFormatter *dateFmt; 

[[inspNotifHour cell] setEntryType:NSPositiveIntType]; /* 1 */ 
[[inspNotifMinute cell] setEntryType:NSPositivelntType]; 
dateFmt = [[NSDateFormatter alloc] /* 2 */ 

initWithDateFormat:@"%m/%d/%y" allowNaturalLanguage:YES]; 

[[inspSchedDate cell] setFormatter:dateFmt]; 

[dateFmt release]; 

[inspPopUp selectltemAtlndex:0]; /* 3 */ 

[inspNotes setDelegate:self] ; 

[[notifView contentView] removeFromSuperview]; /* 4 */ 

notifView = [[notifView contentView] retain]; 

[[reschedView contentView] removeFromSuperview]; 
reschedView = [[reschedView contentView] retain]; 

[[notesView contentView] removeFromSuperview]; 
notesView = [[notesView contentView] retain]; 

[inspectorViews release]; 

[self newInspectorView:self ]; 

} 


ToDoInspector’s awakeFromNib method sets up formatters for the inspector’s 
hour, minute, and date fields. It also performs some necessary “housekeeping” 
tasks. 

1. Sets the hour and minute fields to accept only positive integer values. 

2. Creates a date formatter (an instance of NSDateFormatter) that accepts and 
formats dates as (for example) “12/25/96.” After associating the formatter with 
the date text-field cell, it releases it (setFormatter: retains the formatter). 

3. Makes the Notification display the start-up default, using the index of the 
“Notification” cell rather than its title to improve localization. Then it sets self 
to be the delegate of the text object. 

4. Each of the three inspector displays in the off-screen panel (inspectorViews) is 
the content view of an NSBox. This section of code extracts and retains each 
of those content views, reassigning each to its original NSBox instance 
variable in the process. This explicit retaining is necessary because, in 
newInspectorView:, each currrent content view is released when it’s swapped 
out. Once all content views are retained, the code releases the off-screen 
window and invokes newInspectorView: to put up the default display. 
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Besides responding to events, all objects that inherit from 
NSView can render themselves on the screen. They do this 
rendering through image composition and PostScript drawing. 

NSViews draw themselves as an indirect result of receiving the 
display message (or a variant of display); this message is sent 
explicitly or through conditions that cause automatic display. The 
display message leads to the invocation of an NSView's 
drawRect: method and the drawRect: methods of all subviews of 
that NSView. The drawRect: method should contain all code 
needed to redraw the NSView completely. 

An NSView can be automatically displayed when: 

• Users scroll it (assuming it supports scrolling). 

• Users resize or expose the NSView's window. 

• The window receives a display message or is automatically 
updated. 

• For some Application Kit objects, when an attribute changes. 

An NSView represents a context within which PostScript drawing 
can take place. This context has three components: 

• A rectangular frame within a window to which drawing is 
clipped. 

• A coordinate system 

• The current PostScript graphics state 

Frame and Bounds 

An NSViews frame specifies the location and dimensions of the 
NSView in terms of the coordinate system of the NSView's 
superview. It is a rectangle that encloses the NSView. You can 
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programmatically move, scale, and rotate the NSView by 
reference to its frame (setFrameOrigin:, setFrameSize:, and so 
on). 

To draw efficiently, the NSView must have its frame rectangle 
translated into its own coordinate system. This translated 
rectangle, suitable for drawing, is called the bounds. The bounds 
rectangle usually specifies exactly the same area as the frame 
rectangle, but it specifies that area in a different coordinate 
system. In the default coordinate system, an NSView's bounds is 
the same as its frame, except that the point locating the frame 
becomes the origin of the bounds (x = 0.0, y = 0.0). The x- and y~ 
axes of the default coordinate system run parallel to the sides of 
the frame so, for example, if you rotate the frame the default 
coordinate system rotates with it. 

This relationship between frame and bounds has several 
implications important in drawing and compositing. 

• Each NSView's coordinate system is a transformation of its 
superview's. 

• Drawing instructions don't have to account for an NSView's 
location on the screen or its orientation. 

• Changes in a superview's coordinate system are propagated to 
its subviews. 

NSView allows you to flip coordinate systems (so the positive y- 
axis runs downward) and to otherwise alter coordinate systems. 

Focusing 

Before an NSView can draw it must lock focus to ensure that it 
draws in the correct window, place, and coordinate system. It 
locks focus by invoking NSView's lockFocus method. Focusing 
modifies the PostScript graphics state by: 

• Making the NSView's window the current device 

• Creating a clipping path around the NSView's frame 

• Making the PostScript coordinate system match the NSView's 
coordinate system 

After drawing, the NSView should unlock focus (unlockFocus). 


178 
























Creating and Managing an Inspector (ToDolnspector) 





PostScript Drawing 


In OpenStep, NSViews draw themselves by sending binary- 
encoded PostScript code to the Window Server. The Application 
Kit and the Display PostScript frameworks provide a number of C- 
languagefunctionsthatsend PostScriptcodeto perform common 
drawing tasks. You can use these functions in combinations to 
accomplish fairly elaborate drawing. 

The Application Kit has functions and constants, declared in 
NSGraphics.h, for (among otherthings): 

• Drawing, filling, highlighting, clipping and erasing rectangles 

• Drawing buttons, bezels, and bitmaps 

• Computing window depth and related display information 

You also call OpenStep-compliant drawing routines defined in 
dpsOpenStep.h. These routines (such as DPSDollserPathO) draw 
a specified path. In addition, you can call the functions declared 
in psops.h. These functions correspond to single PostScript 
operators, such as PSsetgrayO and PSfill(). 

You can also write and send your own custom PostScript code, 
pswrap is a program (in /usr/bin) that converts PostScript code 
into C-language functions that you can call within your 
applications. It is an efficient way to send PostScript code to the 
Window Server. The following pswrap function draws grid lines: 


NSViews can simply display an image within their frame. You 
usually composite an image using NSImage's 
compositeToPoint:operation: (or a related method). 

NSImage allows you to copy images into your user interface. It 
uses various subclasses of NSImageRep to store the multiple 
representations of the same image—color, grayscale, TIFF, EPS, 
and so on—and chosing the representation appropriate for a 
given type or display. NSImage can read image data from a 
bundle (including the application's main bundle), from the 
pasteboard, or from an NSData object. 

Compositing allows you to do more than simply copy images. 
Compositing builds a new image by overlaying images that were 
previously drawn. It's like a photographer printing a picture from 
two negatives, one placed on top of the other. Various 
compositing operators (NSCompositingOperation, defined in 
dpsOpenStep.h) determine how the source and destination 
images merge. 

Source Image Destination Image 


Operation Destination After 


defineps DrawGrid(float width, height, every) 

5 6 div 3etgray 
0 every width { 

0 moveto 0 height rlineto stroke 
} for 

0 every height { 

0 exch moveto width 0 rlineto stroke 

> for 
endps 

Compose the function in a file with a .psw extension and add it to 
the Other Source project "suitcase” in Project Builder. When you 
next build your project. Project Builder runs the pswrap program, 
generating an object file and a header file (matching the file name 
of the .psw) file, and links these into the application. To use the 
code, import the header file and call the function when you want 
to do the drawing: 

DrawGrid(5.0, 5.0, 1.0); 


Compositing Images 

The other technique NSViews use to render their appearance is 
image compositing. By compositing (with the SOVER operator) 


Copy 


Source 

Over 


Destination 

Out 


Source image overlays 


Source image wherever 
it is opaque, and 
destination image 
elsewhere. 

Destination image 
wherever it is opaque but 
source image is 
transparent, and 
transparent elsewhere. 


You can achieve interesting effects with compositing when the 
initial images are drawn with partially transparent paint 
(Transparency is specified by coverage, a PostScript indicator of 
paint opacity.) In a typical compositing operation, paint that's 
partiallytransparentwon'tcompletelycoverthe image it's placed 
on top of; some of the other image will show through. The more 
transparent the paint is, the more of the other image you'll see. 
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If you want an o bj e ct th at d raws itself d iff ere ntly than any other Handling Events 

Application Kit object, or responds to events in a special way, you 

should make a custom subclass of NSView. Your custom subclass nex * sec tion, Y° u II make a subclass of NSButtonCell that 

should complete at leastthe steps outlined below. uniquely responds to mouse clicks. The way custom NSViews 

handle events is different. If you intend your custom NSView to 

Note: If you make a custom subclass of any classthat inherits from res P° nd t0 user actions y° u must do a C0U P |e of thin 9 s: 

NSView, and you wantto do custom drawing or event handling, 4 Qverride acce p tS F irs ,Responderto return YES ifthe NSView is 

the basic procedure presented here still applies. to handle selections. (The default NSView behavior is to return 

NO.) 


interface Builder 

1 Define a subclass of NSView in Interface Builder. Then 
generate header and implementation files. 


5 Override the desired NSResponder event methods 

(mouseDown:, mouseDragged:, keyDown:, etc.) 

- (void) mouseDown: (NSEvent *) event { 


2 Drag a CustomView object from the Views palette onto a 
window and resize it Then, with the CustomView object still 
selected, choose the Custom Class display of the Inspector 
panel and select the custom class. Connect any outlets and 
actions. 



if (([event modifierFlags] & 
NSControlKeyMask){ 
doSomething(); 

} 

You can query the NSEvent argument for the location of the user 
action in the window, modifier keys pressed, character and key 
codes, and other information. 

Drawing 

When you send display to an NSView, its drawRect: method and 
each of its subview's drawRect: are invoked. This method is 
where an NSView renders its appearance. 

6 Override drawRect:. The argument is usually the frame 
rectangle in which drawing is to occur. This tells the Window 
Server where the NSView's coordinate system is located. To 
draw the NSView, you can do one or more of the following: 

• Composite an NSImage. 

: 

• Call Application Kit functions such as NSRectFillO and 
NSFrameRect () (NSGraphics.h). 


Initializing Instances 


Override the designated initializer, initWithFrame: to return an 
initialized instance of self. The argument of this method is the 
frame rectangle of the NSView, usually as set in Interface 
Builder (see step 2). You might want to display the customview 
at this point. 

IJlSh^V ; 

' ' i ' f;: -Hi. 

. . . I ...::.■ 


• Call C functions that correspond to single PostScript 
operations, such as PSsetgrayO and PSfillO, 

• Call custom drawing functions created with pswrap. 

See "A Short Guide to Drawing and Compositing" on page 179 for 
more information on drawing techniques and requirements. 


mum 


180 











Subclass Example: Overriding and Adding Behavior (ToDoCell) 


Subclass Example: Overriding and Adding Behavior (ToDoCell) 


Buttons in the Application Kit are two-state controls. They have two—and only 
two—states: 1 and 0 (often expressed as Boolean YES and NO, or ON and 
OFF). For the To Do application, a three-state button is preferable. You want 
the button to indicate, with an image, three possible states: notDone (no image), 
done (an “X”), and deferred (a check mark). These states correspond to the 
possible statues of a ToDoItem. 

The ToDoCell class, which you will implement in this section, generates cells 
that behave as three-state buttons. These buttons also display the time an item 
is due. 


item status . - jjx 05:45 PM 


Time item is due. 


The superclass of ToDoCell is NSButtonCell. In creating ToDoCell you will 
add data and behavior to NSButtonCell, and you will override some existing 
behavior. 


Why Chose NSButtonCell as Superclass? 


ToDoCell's superclass is NSButtonCell. This 
choice prompts two questions: 

• Why a button cell and notthe button itself? 

• Why this particular superclass? 

NSCell defines state as an instance variable, 
and thus ail cells inherit it Cells instead of 
controls hold state information for reasons of 
efficiency—one control (a matrix) can 
manage a collection of cells, each cell with 
its own state setting. NSButton does provide 
methods for getting and setting state values, 
but it accesses the state value of the cell 
(usually NSButtonCell) that it contains. 


NSButtonCell is ToDoCell's superclass 
because button cells already have much of 
the behavior you want By virtue of 
inheritance from NSActionCell, button cells 
can hold target and action information. 
Button ceils also have the unique capability 
to display an image and text simultaneously. 
These are all aspects of behavior needed for 
ToDoCell. 

When you think that you need a specialized 
subclass of an OpenStep class, you should 
first spend some time examining the header 
files and reference documentation on not 
only that class, but its superclasses and any 
"sibling" classes. 
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1 Add header and implementation 
files to the project. 

Chose New in Project from the 
File menu. 

In the New File In ToDo panel, 
select the Class suitcase, click 
Create header, type "ToDoCeH" 
after Name, and click OK. 

2 Complete ToDoCell.h. 

Make the superclass 
NSButtonCell. 

Add the instance-variable and 
method declarations shown at 
right. 

Add the enum constants for state 
values (as shown). 


3 Initialize the allocated ToDoCell 
instance (and deallocate it). 

Select ToDoCell.m in the project 
browser. 

Implement init as shown at right. 
Implement dealloc. 


enum _ToDoButtonState {notDone=0, done, deferred} ToDoButtonState; 

(^interface ToDoCell : NSButtonCell 

{ 

ToDoButtonState triState; 

NSImage *doneImage, *deferredlmage; 

NSDate *timeDue; 

} 

- (void)setTriState:(ToDoButtonState)newState; 

- (ToDoButtonState)triState; 

- (void)setTimeDue:(NSDate *)newTime; 

- (NSDate *)timeDue; 

@end 

The triState instance variable will be assigned ToDoButtonState constants as 
values. The NSImage variables hold the “X” and check mark images that 
represent statuses of completed and deferred (that is, rescheduled for the next 
day). The timeDue instance variable carries the time the item is due as an 
NSDate; for display, this object will be converted to a string. 

- (id)init 

{ 

NSString *path; 

[super initTextCell:@” ” ] ; 

triState = notDone; 

[self setType-.NSToggleButton] ; /* 1 */ 

[self setlmagePosition:NSImageLeft]; 

[self setBezeled:YES]; 

[self setFont:[NSFont userFontOfSize:12]]; 

[self setAlignment:NSRightTextAlignment]; 

/* 2 */ 

path = [[NSBundle mainBundle] pathForlmageResource:@"X.tiff"]; 
donelmage = [[NSImage alloc] initByReferencingFile:path]; 
path = [[NSBundle mainBundle] 

pathForlmageResource:@"checkMark.tiff”]; 
deferredlmage = [[NSImage alloc] initByReferencingFile:path]; 

return self; 

) 


1. Sets some superclass (NSButtonCell) attributes, such as button type, image and 
text position, font of text, and border. 

2. Through NSBundle’s pathForlmageResource:, gets the pathname for the cell 
images and creates and stores the images using the pathname. 
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4 Implementthe accessor methods 
related to state. 

Write the methods that get and 
set the triState instance variable. 

Override the superclass methods 
that get and set state. 


- {void)setTriState:(ToDoButtonState)newState 
{ 

if (newState == deferred+1) 
triState = notDone; 

else 

triState = newState; 

[self _setlmage:triState] ; 

} 

- (ToDoButtonState)triState {return triState;} 

- (void)setState:(int)val 
{ 

} 


- (int)state 
{ 

if (triState == deferred) 
return (int)done; 

else 

return (int)triState; 


/* 1 */ 


/* 2 */ 


/* 3 */ 


Accessing state information is a dual-path task in ToDoCell. It involves not only 
setting and getting the new state instance variable, triState, but properly handling 
the inherited instance variable by overriding the superclass accessor methods for 
state. 

1. If the new value for triState is one greater than the limit (deferred), reset it to zero 
(notDone); otherwise, assign the value. The reason behind this logic is that (as 
you’ll soon learn) when users click a ToDoCell, setTriState: is invoked with an 
argument one more than the current value. This way users can cycle through the 
three states of ToDoCell. 

2. Overrides setState: to be a null method. The reason for this override is that 
NSCell intervenes when a button is clicked, resetting state to zero (NO). 
This override nullifies that effect. 

3. Overrides state to return a reasonable value to client objects that invoke this 
accessor method. 
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5 Set the cell image. 

Declare the private method 
_setlmage:. 

Implement the _setlmage: 
method. 


©interface ToDoCell (PrivateMethods) 

- (void)_setlmage:(ToDoButtonState)aState; 

©end 

/* ... ■*/ 

- (void)_setlmage:(ToDoButtonState)aState 
{ 

switch(aState) { 
case notDone: { 

[self setlmage:nil]; 
break; 

} 

case done: { 

[self setlmage:donelmage]; 
break; 

} 

case deferred: { 

[self setlmage:deferredlmage]; 
break; 

} 

} 

[(NSControl *)[self controlView] updateCell:self]; 

} 


/* 1 */ 


/* 2 */ 


./* 3 */ 


This portion of code handles the display of the cell’s image by doing the 

following: 

1. In a category of ToDoCell in ToDoCell.m, it declares the private method _setlmage:. 
Private methods, which by convention begin with an underscore, are methods that 
you don’t want clients of your object to invoke. In this case, you don’t want the 
image to be set independently from the cell’s triState value. 

2. In a switch statement, evaluates the tri-state argument and sets the cell’s 
image appropriately (setlmage: is an NSButtonCell method). 

3. Sends updateCell: to the control view of the cell’s control (a matrix) to force a 
re-draw of the cell. 
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6 Track mouse clicks on a 
ToDoCell and reset state. 

Override two NSCell mouse¬ 
tracking methods as shown in this 
example. 


7 Get and set the time due, 
displaying the time in the 
process. 

ImplementsetTimeDue: as shown 
in this example. 

Implement timeDue to return the 
NSDate. 


- (BOOL)startTrackingAt:(NSPoint)startPoint inView: 

(NSView *)controlView 

{ 

return YES; 

} 

- (void)stopTracking:(NSPoint)lastPoint at:(NSPoint)stopPoint 
inView:(NSView *)controlView mouselsUp:(BOOL)flag 

{ 

if (flag == YES) { 

[self setTriState:([self triState] +1) ] ; 

} 

} 

When you create your own cell subclass, you might want to override some 
methods that are intrinsic to the behavior of the cell. Mouse-tracking methods, 
inherited from NSCell, are among these. You can override these methods to 
incorporate specialized behavior when the mouse clicks the cell or drags over it. 
ToDoCell overrides these methods to increment the value of triState. 

• Overrides startTrackingAt:inView: to return YES, thus signalling to the control 
that the ToDoCell will track the mouse. 

• Overrides stopTracking:at:inView:mouselsUp: to evaluate flag and, if it’s YES, to 
increment the triState instance variable. (The setTriState: method “wraps” the 
incremented value to zero (notDone) if it is greater than 2 (deferred)). 


- (void)setTimeDue:(NSDate *) newTime 
{ 


if 

(timeDue) 



[timeDue 

autorelease]; 

if 

(newTime) 

{ 


timeDue = 

[newTime copy] 


[self setTitle:[timeDue descriptionWithCalendarFormat: 
@"%I:%M %p" timeZone:[NSTimeZone localTimeZone] 
locale:nil]]; 

} 

else { 

timeDue = nil; 

[self setTitle:@; 

> 

|r } 

The setTimeDue: method is similar to other “set” accessor methods, except that it 
handles interpretation and display of the NSDate instance variable it stores. If 
newTime is a valid object, it uses NSDate’s 

descriptionWithCalendarFormat:timeZone:locale: method to interpret and format the 


185 



Chapter 4 


To Do Tutorial 


date object, then displays the result with setTitle:. If newTlme is nil, no due time has 
been specified, and so the method sets the title to 

You’ve now completed all code required for ToDoCell. However, you must now 
“install” instances of this class in the To Do interface. 


8 At launch time, create and install 
your custom cells in the matrix. 

Select ToDoDoc.m in the project 
browser. 

Insert the code at right in 

awakeFromNib. 


- (void)awakeFromNib 
{ 

int i; 

/* ... */ 

i =' [ [markMatrix cells] count] ; 
while (i—) { 

ToDoCell *aCell = [[ToDoCell alloc] init]; 
[aCell setTarget:self]; 

[aCell setAction:©selector{itemChecked:)]; 
[markMatrix putCell:aCell atRow:i column :0]; 
[aCell release]; 

} 

> 


This block of code substitutes a ToDoCell for each cell in the left matrix 
(markMatrix) you created for the To Do interface. It creates a ToDoCell, sets its 
target and action message, then inserts it into the markMatrix by invoking 
NSMatrix’s putCell:atRow:coIumn: method. 

Finally, you must implement the action message sent when the matrix of 
ToDoCells is clicked. (This response to mouse-down is for objects external to 
ToDoCell, while the mouse-tracking response sets state internally.) 


9 Respond to mouse clicks on the 
matrix of ToDoCell's. 

In ToDoDoc.m, implement 
itemChecked:. 


- (void)itemChecked:sender 
{ 

int row = [sender selectedRow]; 

ToDoCell *cell = [sender cellAtRow:row column:0]; 
if (cell && [currentltems count]) { 

id item = [currentltems objectAtlndex:row]; 
if (item && [item isKindOfClass:[ToDoItem class]]) { 
[item setltemStatus:[cell tristate]]; 

[[sender window] setDocumentEdited:YES]; 

} 

} 

} 


This method gets the ToDoCell that was clicked and the object in the 
corresponding text field. If that object is a ToDoItem, the method updates its 
status to reflect the state of the ToDoCell. It then marks the window as 
containing an edited document. 
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Setting Up Timers for Notification Messages 

The To Do application includes as a feature the capability for notifying users of 
items with impending due times. Users can specify various intervals before the 
due time for these notifications, which take the form of a message in an attention 
panel. In this section you will implement the notification feature of To Do. In 
the process you’ll learn the basics of creating, setting, and responding to timers. 

Here’s how it works: Each ToDoItem with a “When to Notify” switch (other 
than “Do not notify”) selected in the inspector panel—and hence has a positive 
secslintilNotif value—has a timer set for it. If a user cancels a notification by 
selecting “Do not notify,” the document controller invalidates the timer. When 
a timer fires, it invokes a method that displays the attention panel, selects the 
“Do not notify” switch, and sets secsUntilNotif to zero. 

Implementing the timer feature takes place entirely in Project Builder, but 
extends across several classes. 


1 Add the timer as an instance 
variable to ToDoItem. 

OpenToDoltem.h. 

Add the instance variable 
itemlimer of class NSTimer. 

Write accessor methods to get 
and set this instance variable. 

2 Create and set the timer, or 
invalidate it. 

OpenToDoDoc.m. 

Implement the setTlmerForltem: 
method, which is shown at right. 


- (void)setTimerForltem: (ToDoItem *)anltem 
{ 

NSDate *notifDate; 

NSTimer *aTimer; 

if ([anltem secsUntilNotif]) { /* 1 */ 

notifDate = [[anltem day] addTimelnterval:[anltem 
secsUntilNotif]]; 

aTimer - [NSTimer scheduledTimerWithTimelnterval: /* 2 */ 

[notifDate timelntervalSinceNow] 
target:self 

selector:©selector(itemTimerFired:) 
userlnfo:anltem 
repeats;NO]; 

[anltem setltemTimer:aTimer]; 

} else 

[[anltem itemTimer] invalidate]; /* 3 */ 


This method sets or invalidates a timer, depending on whether the ToDoItem 
passed in has a positive secsUntilNotif value. 

1. Tests the ToDoItem to see if it has a positive secsUntilNotif value and, if it has, 
composes the time the notification should be sent. 

2. Creates a timer and schedules it to fire at the notification time, and instructs 
it to invoke itemTimerFired: when it fires. It also sets the timer in the ToDoItem. 

3. If the secsUntilNotif variable is zero, invalidates the item’s timer. 
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3 Respond to timers firing. 

Implement itemTimerFired: as 
shown at right 


- (void)itemTimerFired:(id)timer 
( 

id anltem = [timer userlnfo]; 

ToDoInspector *inspController"= 
inspector] delegate]; 

NSDate *dueDate =[[anltem day] 

[anltem secsUntilDue]]; 

NSBeep(); 

NSRunAlertPanel(@"To Do", @"%@ on %@", nil, nil, nil, 

[anltem itemNameJ, [dueDate 

descriptionWithCalendarFormat:@”%b %d, %Y at %I:%M %p" 
timeZone:[NSTimeZone defaultTimeZone] locale:nil]); 

[anltem setSecsUntilNotif:0]; 

[inspController resetNotifSwitch]? 

} 

When a ToDoItem’s timer goes off, it invokes the itemTimerFired: method 
(remember, you designated this method when you scheduled the timer). 

1. This method communicates with ToDoInspector in a more direct manner than 
notification. It gets the ToDoInspector object through this chain of association: the 
delegate of the application object is ToDoController, which holds the id of the 
inspector panel as an instance variable, and the delegate of the inspector panel is 
ToDoInspector. 

2. Composes the notification time (as an NSDate), beeps, and displays an 
attention panel specifying the name of a ToDoItem and the time it is due. It 
then sets the ToDoItem’s secslintilNotif instance variable to zero, and sends 
resetNotifSwitch to ToDoInspector to have it reset the “When to Notify” 
switches to “Do not Notify.” 

Before You Go On -- 

Implement resetNotifSwitch: You haven’t written ToDoInspector’s resetNotifSwitch 

method yet, so do it now as an exercise. It should select the “Do not Notify” 
switch after turning off all switches in the matrix, and then force a redisplay of 
the switch matrix. 


[[[NSApp delegate] 
addTimelnterval: 




/* 1 */ 
/* 2 */ 


Next you must send setllmerForltem: at the right place and time, which is 
ToDoInspector, when the user alters a “When to Notify” value. 


188 



Setting Up Timers for Notification Messages 


4 Send the message that sets the 
timer at the right times 


[ [[NSApp mainWindow] delegate] setTimerForltem:currentltem]; 


Open ToDolnspector.m. 

In switchChecked:, insert the 
setTimerForltem: message at 
right afterthe switch statement 
evaluating which "When to 
Notify" switch was checked. 

In controlTextDidEndEditing:, 

insert the same message at the 
end of the block related to the 
inspNotifOtherHours variable. 

5 When the application is 
launched, reset item timers. 

Add the code at right, below, to 
ToDoDoc's initWithFile: method. 


Instead of archiving an item’s NSTimer, To Do re-creates and resets it when the 
application is launched. 

if ([self activeDays]) { 

dayenum = [[self activeDays] keyEnumerator]; 
while (itemDate = [dayenum nextobject]) { 

NSEnumerator *itemenum; 

ToDoItem *anltem=nil; 

NSArray *itemArray = [[self activeDays] 
objectForKey:itemDate]; 
itemenum = [itemArray objectEnumerator]; 
while ((anltem = [itemenum nextobject]) && 

[anltem isKindOfClass:[ToDoItem class]] && 
[anltem secsUntilNotif]) { 

[self setTimerForltem:anltem]; 

} 

} 


This block of code traverses the activeDays dictionary, evaluating each ToDoItem 
within the dictionary. If the ToDoItem has a positive secsUntilNotif value, it 
invokes setTimerForltem: to have a timer set for it. 


Tick Tock Brrrring: Run Loops and Timer 

A run loop—an instance of NSRunLoop— i 
manages and processes sources of input. i 
These sources include mouse and keyboard 
events from the window system, file I 

descriptor, inter-thread connections 
(NSConnection), and timers (NSTimer). 

Applications typically won't need to either 
create or explicitly manage NSRunLoop i 
objects. When a thread is created, an 
NSRunLoop object is automatically created 
for it. The NSApplication object creates a 
default thread and therefore creates a 
default run loop. 

NSTimer creates timer objects. A timer i 

object waits until a certain time interval has 


elapsed and then fires, sending a specified 
message to a specified object. For example, 
you could create an NSTimer that 
periodically sends messages to an object, 
asking it to respond if an attribute changes. 

NSTimer objects work in conjunction with 
NSRunLoop objects. NSRunLoops control 
loops that wait for input, and they use 
NSTimers to help determine the maximum 
amount of time they should wait. When the 
NSTimer's time limit has elapsed, the 
NSRunLoop fires the NSTimer (causing its 
message to be sent), then checks for new 
input. 
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Build, Run, and Extend the Application 

Although you probably have been building the ToDo project frequently now, as 
it’s been taking shape, build it one more time and check out what you have 
wrought. Go through the following sequence and observe To Do’s behavior. 

1. When you choose New from the Document menu, the application creates a new 
To Do document and selects the current day. 

2. Enter a few items. Click a new day on the calendar and enter a few more 
items. Click the previous day and notice how the items you entered reappear. 

3. Choose Inspector from the main menu. When the inspector appears, click an 
item and notice how the name and date of the item appears in the top part of 
the inspector. Enter due times for a couple items, and some associated notes. 
Note how the times, as you enter them, appear in the Status/Due column of 
the To Do document. Click among a few items again and note how the 
Notifications and Notes displays change. 

4. Click a Status/Due button; the image toggles among the three states. Then, 
with an item that has a due time, select a notification time that has already 
passed. The application immediately displays an attention panel with a 
notification message. When you dismiss this panel, To Do sets the 
notification option to “Do not notify.” 

5. Click the document window and respond to the attention panel by clicking 
Save. In the Save panel, give the document a location and name. When the 
window has closed, chose Open from the Document menu and open the 
same document. Observe how the items you entered are redisplayed. 

Optional Exercises 

You should be able now to supplement the To Do application with other 
features and behaviors. Try some of the following suggestions. 

Make Your Own Info Panel 

Make your own Info panel. Define a method that responds to a click on the Info 
panel button by loading a nib file containing the panel. The owner of the panel 
can be the application controller. You can customize this panel however you 
wish. For instance, put the application icon in a toggled button (the main image) 
and make the alternate image a photo (yourself, your significant other, your 
dog). When users click the button, the image changes between the two. 
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Implement Application Preferences 

Make a Preferences panel for the application, with a new controller object (or 
the application controller) as the owner of the nib file containing the panel. 
Follow what you’ve done for ToDoInspector, especially if the panel has 
multiple displays. Some ideas for Preferences: how long to keep expired 
ToDoItems before logging and purging them (see below); the default document 
to open upon launch; the default rescheduling interval (see below). Store and 
retrieve specified preferences as user defaults; for more information, see the 
NSUserDefaults specification. 

Implement Rescheduling 

ToDo’s Inspector pane has a Rescheduling display that does almost nothing 
now. Implement the capability for rescheduling items by the period specified. 

Implement Logging and Purging 

After certain period (set via Preferences), append expired ToDoItems (as 
formatted text) to a log, and expunge the ToDoItems from the application. 
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If you’ve completed the tutorials in this book, you’re no longer a novice in 
OpenStep development. You should be able to attempt an OpenStep 
application on your own, and should expect to carry it off successfully. However, 
there is much more for you to learn (or to learn in greater detail). There will 
probably be times when you’ll need information or help. You might want to 
pursue a training course, you might want to order a NeXT product, or you might 
have questions you’ll need answered, or problems you’ll need resolved. 

This section points you toward these sources of information and help. It also 
includes descriptions of tools, resources, and documentation frequently used in 
application development. 

World Wide Web 

NeXT’s corporate home page is at: http://www.next.com. 

From there you can navigate to summaries of products, such as WebObjects®, 
Enterprise Objects Framework®, and D’OLE®—and order the products on¬ 
line. You can learn about NeXT programs in education, consulting and technical 
support. You can also use the NeXTanswers document retrieval system. For 
WebObjects, you can download versions of the product, try out demonstration 
WebObjects applications, and access related documentation. 
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Programming Tools and Resources 

Other Development Applications 

OPENSTEP Developer for Mach includes applications other than Project 
Builder and Interface Builder. Except where noted, these applications are 
installed in /NextDeveloper/Apps. 


Name 

Description 

FileMerge 

Visually compares the contents of two files or two directories. You can use 
FileMerge, for example, to determine the differences between versions of the 
same source code file or between two project directories. You can also use it 
to merge changes. 

MallocDebug 

Measures the dynamic-memory usage of applications, finds memory leaks, 
analyzes all allocated memory in an application, and measures the memory 
allocated since a given time. 

IconBuilder 

A simple graphics program for creating application and document icons. 

Yap 

A utility for editing and previewing PostScript code. 

Sampler 

Analyzes performance problems with your application by sampling the call 
stack of your program over a period. (In /NextDeveloper/Demos) 


Other Installed Frameworks 

A framework contains a dynamic shared library, related header files, and 
resources (including nib files, images, sounds, documentation, and localized 
strings) used by the library. All frameworks are installed in/NextLibrary/Frameworks. 
OPENSTEP Developer for Mach provides these other frameworks in addition 
to the Application Kit and the Foundation frameworks: 


Name 

Description 

System 

Operating-system and low-level Objective-C runtime APIs 

SoundKit 

Sound recording, playback, and editing capabilities. 

InterfaceBuilder 

Creation of custom static (compiled) palletes for use in Interface Builder 

NEXTIME 

Real-time video imaging 

NIAccess 

Netlnfo's access layer 

Nllnterface 

IMetlnfo's interface layer 
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Useful Command-Line Tools 

NeXT has created or modified several tools for compilation, debugging, 
performance analysis, and so on. The following table lists some of the more 
useful of these tools. You can get further information using the man pages 
system. 


Name 

Description 

Location 

cc 

Compiles C, Objective-C, C++, and Objective-C++ 
source code files. 

/bin 

gdb 

Source-level symbolic debugger for C, extended by 
NeXT to support Objective-C, C++, Mach, Windows NT, 
and (by late 1996) Windows 95. 

/bin 

gnumake 

Utility for making programming projects. 

/bin 

as 

Assembler; translates assembly code into object code. 

/bin 

defaults 

Reads, writes, searches, and deletes user defaults. 

The defaults system records user preferences that 
persist when the application isn't running. When users 
specify defaults in an application's Preferences panel, 
NSUserDefaults methods are used to write the defaults. 

/usr/bin 

pswrap 

Creates C functions that "wrap" PostScript code and 
send it to the Window Server for interpretation. 

/usr/bin 

nibTool 

Reads the contents of an Interface Builder nib file. 

Prints classes, the hierarchy, objects, connections, and 
localizable strings. 

/usr/bin 

libtool 

Creates static or dynamic libraries from specified 
object bin files for one or multiple architectures. 


otool 

Displays specified parts of object files or libraries. 

/bin 

nm 

Displays the symbol table, in whole or in part, of the 
specified object file or files. 

/bin 

oh 

Records allocation and deallocation events. 

/usr/bin 

AnalyzeAllocation 

Analyzes program memory allocation. 

/usr/bin 

fixPrecomps 

Creates a precompiled header file for each of the major /usr/bin 
frameworks. 

strip 

Removes or modifies the symbol table attached to 
assembled and linked output. 

/bin 

lipo 

Creates, lists, and manipulates multi-architecure 
object files 

/bin 
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Converting NEXTSTEP Code to OPENSTEPp 

You can take advantage of an automated conversion process to convert 
NEXTSTEP® Release 3.# code to OPENSTEP Release 4.0. By completing 
this process you’ll make your application an OpenStep application (that is, an 
application conforming to the OpenStep specification). An OpenStep 
application—one without any specific operation-system dependencies— 
should run on any OpenStep system. 

The TOPS scripts you run to perform the conversion process, along with 3.3 
header files and intermediate frameworks, are located at 
/NextDeveloper/OpenStepConversion. The OPENSTEP Conversion Guide provides 
instructions on using the scripts as well as summaries of API changes and 
conversion tips. 

Other Programming Resources 

You can find programming resources—such as fonts, sounds, and palettes—in 
various subdirectories of /NextLibrary. 


Name 

Comments 

SystemResources 

Character-set information and location of headers for automatic 
precompilation (flxPrecomps) 

Colors 

Bundles containing the default set of color binaries for the Colors panel 

Fonts 

Default set of system fonts, including AFM, bitmap, and outline versions 

PS2Resources 

PostScriptfiles containing calibrated colorspace and color rendering, printing 
halftones, and gray-shading patterns 

Rulebooks 

Glyph generators for various string encodings 

Sounds 

Default sound files (".snd") such as Cricket, Ping, and Rooster 
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Information 


NeXT publishes documentation for users, developers, and system 
administrators. It also, through its Professional Services, offers customers access 
to NeXTanswers, an automated document retrieval system. 

To order documentation, call 1-800-TRY-NEXT 


Accessing Documentation 

On OPENSTEP for Mach, several tools help you access documentation: 


For more information on Digital 
Librarian and on other means for 
accessing documentation, see 
“Where To Go For Help” on 
page 54. 

For details of using the Project 
Find panel, see “Finding 
Information Within Your Project” 
on page 94. 


• Digital Librarian’s NextDeveloper bookshelf includes most of the documents 
described in “Developer Documentation” below, as search targets. This 
bookshelf, which located at /NextLibrary/Bookshelves, also includes instructions 
for creating your own custom bookshelf. 

• In Project Builder, you can use the Project Find panel to display reference 
documentation on classes, protocols, methods, functions, and other types. 

• In Project Builder or in a Terminal window, you can issue commands to 
UNIX’s man pages system to display information on command-line tools. 

Developer Documentation 

The core set of documentation for OPENSTEP is the reference specifications 
describing OpenStep classes, protocols, methods, functions, types, and 
constants.The reference documentation for the two major OpenStep 
frameworks is stored within the frameworks: 


/NextLibrary/Frameworks/AppKit.framework/Resources/English.lproj/Documentation 

/NextLibrary/Frameworks/Foundation.framework/Resources/English.lproj/Documentation 

Several documents—some printed but most only in on-line form—supplement 
this core set of documentation. The following table describes these materials 
directly related to OPENSTEP for Mach; all documents are located at 

/NextLibrary/Documentation/NextDeu 
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Book/Document 

Description 

/NexDev Directory 

Object-Oriented 
Programming and the 
Objective-C Language 

Title says it all 

TasksAndConcepts 
(as ObjectiveC) 

OPENSTEP Development: Using Project Builder, Interface Builder, and other 
Tools and Techniques tools in program development 

TasksAndConcepts 
(as DevEnvGuide) 

Programming Topics 

Contains conceptual background and step-by-step 
instructions for common programming tasks. 

(Note: the numbered of covered topics will grow in 
the months following release 4.0.) 

TasksAndConcepts 

General Reference 

Display PostScript reference documentation plus 
information pertinent to all OpenStep frameworks 

Reference 

Release Notes 

Current release notes on frameworks, development 
applications, and tools 

ReleaseNotes 


Other Developer Documentation 

If you’ve installed Enterprise Objects Framework or Portable Distributed 
Objects documentation for these products will also be installed in 
/NextLibrary/Documentation/NextDeu This includes the API reference and Developer's 
Guide {ox Enterprise Objects Framework. 

You will also find third-party documentation installed in 
/NextLibrary/Documentation, including reference documentation for the GNU 
libg++ (C++) library. 

System Administration Do<umentation 

Documentation for system administrators of OPENSTEP for Mach networks 
can find a helpful manual in /NextLibrary/Documentation/NextAdmin. This manual 
describes planning and setting up networks, as well as the creation of user 
accounts. It also explains details of NFS, discusses administrative tasks such as 
backups and security, and provides troubleshooting guidelines. 

In /NextLibrary/Documentation, you’ll also find back issues of the magazine for 
system administrators, NEXTSTEP In Focus. 


NeXT’s Professional Services 
also distributes OpenStep 
programming information 
through NeXTanswers, an 
automated document retrieval 
system. See page 204 for details. 
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Professional Services 

NeXT provides training, consulting, and technical support for its customers. For 
more information on the programs described below, call 1-800-955-NEXT 
(U.S.), +1 415-780-2922 (elsewhere in North America), +44 181-565-0005 
(Europe). You can also visit the Professional Services section of the NeXT 
website at http://www.next.com/Services for up-to-date information on current 
programs in technical education, consulting, and support. 

Education 

Courses offered by NeXT’s Training department give developers of all 
backgrounds a strong foundation in the fundamentals of OpenStep application 
development. This background is critical to the successful implementation of 
OpenStep programs by development teams. 

Customers can choose from three training formats: 

• Open enrollment classes, held at NeXT’s training facilities in Redwood City, 
Washington, D.C., and Chicago 

• On-site classes at the customer’s location 

• On-site Object Learning Solutions, which over periods of several weeks 
provide customers with training and tailored development of skills. 

Object Expert Consulting 

The Object Expert program assigns an expert in OpenStep development to 
assist customers in their projects on a full-time basis. The committment can be 
from two months to as many months as necessary. The Object Expert can help 
with developing a prototype (including project planning, requirements, 
integration, and testing) or can provide analysis, design, planning, programming, 
integration, and testing expertise for full-fledged application-development 
projects. 

Software Maintenance and Technical Support 

With the Software Maintenance program customers can get one copy of each 
covered release of software and documentation as well as major and minor 
software upgrades. They can select from four levels of technical support and 
software maintenance offered by NeXT 

Support includes a range of offerings, from installation assistance to 
NeXTanswers. Developers receive debugging assistance and problem 
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investigation, memory management and performance tuning, portability advice, 
and help with converting NEXTSTEP code to OpenStep. System 
administrators can obtain help with problems related to network connectivity, 
Netlnfo domain requirements analysis and implementation, hardware selection 
and configuration questions, and other areas. 

NeXTanswers 

NeXTanswers is an automated retrieval system that gives customers access to 
the latest product information, technical documents, drivers, and other software. 
You can access NeXTanswers through NeXT’s website (http://www.next.com) and 
by: 

• Electronic mail: Send requests to nextanswers@next.com with a subject line of 
HELP to receive instructions on how to proceed. 

• Fax: Call 415-780-3990 from a touch-tone phone and follow instructions 
(you’ll need to know the ID numbers of the files you want). 

• Anonymous FTP: Connect to FTP.NEXT.COM and read 
pub/NeXTanswers/README for further instructions. 

• BBS: Call 415-780-2965, log in as “guest”, and go to the Files section. From 
there you can download NeXTanswer documents. 

Requests sent to NeXTanswers are answered electronically, and are not read or 
handled by a person. It does not answer your questions or forward your requests. 
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Ordering NeXT Products and Services 

To order NeXT products and services, you can: 

1. Call 1-800-TRY-NEXT (U.S. only); a sales representative will assist you. 

2. Send electronic mail to trynext@next.com. 

3. Fill out the on-line form on the World Wide Web at 
http://www.next.com/AboutNext/Feedback.html and a sales representative will 
promptly contact you. 

4. Contact one of the sales offices below, which can also furnish you with 
product brochures, data sheets, and other information. 

Worldwide Headquarters 

900 Chesapeake Drive 

Redwood City, CA 94063 

Tel: (415) 366-0900 

Fax: (415)780-3714 


North American Field Sales Offices 

Washington DC Office 

1650 Tysons Boulevard, Suite 650 
McLean, VA 22102 
Tel: (703) 938-6398 
Fax: (703) 506-3990 


New York Office 

One Park Avenue, Sixth Floor 
New York, NY 10016 
Tel: (212) 503-4750 
Fax: (212) 503-4751 


New Jersey Office 

90 Washington Valley Road 
Bedminister, NJ 07921 
Tel: (908) 719-8905 
Fax: (908) 719-8903 
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Chicago Office 

311 South Wacker Drive, 22nd Floor 

Suite 2250 

Chicago, IL 60606 

Tel: (312) 697-4500 

Fax: (312) 697-4501 


Canadian Office 

4370 Dominion Street 
Suite 400 

Burnaby, British Columbia 
Canada V5G-4L7 
Tel: (604) 451-1877 
Fax: (604) 451-1819 


Mexico (MeXT) 

Tel: 011 525-530-7278 

European and Asian Sales Offices 

NeXT Computer UK Limited 

Technology House 
Meadow Bank 
Furlong Road 
Bourne End 
Bucks 
SL8 5AJ 

Tel:* 44(0) 1628 535222 
Fax:+44(0) 1628 535200 


NeXT Computer Paris, France 

TourCBC 
8rue Felix Pyat 
F-92800 Puteaux la Defense 
Tel: (+33) 1 46 93 27 82 
Fax: (+33) 1 46 93 29 28 


NeXT Software K.K. (Asia Pacific) 

Tennoz Central Tower 7F 
2-2-24 Higashi-Shinagawa 
Shinagawa-ku, Tokyo 
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140 Japan 

Tel: +81-3-5461-7161 
Fax: +81-3-5461-7170 


NeXT Software Deutschland GmbH 

Gruenwalder Weg 13a 
D-82008 Unterhaching 
Germany 

Tel: +49 89 614 529 0 
Fax: +49 89 614 529 12 
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“Object-oriented programming” has become one of the premier buzzwords in 
the computer industry. To understand why, it’s important to cut through the 
hype and focus on the problem that engendered the object-oriented approach. 

In classic procedural programming (used with COBOL, Fortran, C, and other 
languages), programs are made of two fundamental components: data and code . 
The data represents what the user needs to manipulate, while the code does the 
manipulation. To improve project management and maintenance, procedural 
programs compartmentalize code into procedures . However, much of the data is 
global, and each procedure may manipulate any part of that global data directly. 



With the procedural approach, the network of interaction between procedures 
and data becomes increasingly complex as an application grows. Inevitably, the 
interrelationships become a hard-to-maintain tangle—spaghetti code. A simple 
change in a data structure can affect many procedures, many lines of code—a 
nightmare for those who must maintain and enhance applications. Procedural 
programming also leads to nasty, hard-to-find bugs in which one function 
inadvertently changes data that another function relies on. 

Objects change all that. 
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Objects 


An object is a self-contained programmatic unit that combines data and the 
procedures that operate on that data. In the Objective-G language, an object’s 
data comprises its instance variables, and its procedures, the functions that affect 
or make use of the data, are known as methods. 

Like objects in the physical world, objects in a program have identifying 
characteristics and behavior. Often programmatic objects are modelled on real 
objects. For example, an object such as a button has an analog in the buttons on 
control devices, such stereo equipment and telephones. A button object 
includes the data and code to generate an appearance on the screen that 
simulates a “real” button and to respond in a familiar way to user actions. 


A button object highlights its on-screen representation 
when the user clicks it 


Button 

Button ^ 

.-..... .. V .J 


Encapsulation 

Just as procedures compartmentalize code, objects compartmentalize both code 
and data. This results in data encapsulation , effectively surrounding data with the 
procedures for manipulating that data. 

Typically, an object is regarded as a “black box,” meaning that a program never 
directly accesses an object’s variables. Indeed, a program shouldn’t even need to 
know what variables an object has in order to perform its functions. Instead, the 
program accesses the object only through its methods. In a sense, the methods 
surround the data, not only shielding an object’s instance variables but 
mediating access to them: 



Objects are the basic building blocks of Objective-C applications. By 
representing a responsibility in the problem domain, each object encapsulates a 
particular area of functionality that the program needs. The object’s methods 
provide the interface to this functionality. For example, an object representing 
a database record both stores data and provides well-defined ways to access that 
data. 
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Using this modularity\ object-oriented programs can be divided into distinct 
objects for specific data and specific tasks. Programming teams can easily parcel 
out areas of responsibility among them, agreeing on interfaces to the distinct 
objects while implementing data structures and code in the most efficient way 
for their specific area of functionality. 

Messages 

To invoke one of the object’s methods you send it a message . A message requests 
an object to perform some functionality or to return a value. In Objective-C, a 
message expression is enclosed in square brackets, like this: 


Celsius = [converter convertTemp:fahrenheit] 

'-y-' v -v-' v -v-' v -v-' 

returned value receiver method name argument 

In this example converter is the object that receives the message, the receiver ; 
Everything to the right of this term is the message itself; it consists of a method 
name and any arguments the method requires. The message received by 
converter tells it to convert a temperature in Fahrenheit to Celsius and return that 
value. 

In Objective-C, every message argument is identified with a label. Arguments 
follow colon-terminated keywords , which are considered part of the method 
name. One argument per keyword is allowed. If a method has more than one 
argument—as NSString’s rangeOfString:options: method does, for example— 
the name is broken apart to accept the arguments: 

range = [string rangeOfString:@"OPENSTEP" options:NSLiteralSearch]; 

Often, but not always, messages return values to the sender of the message. 
Returned values must be received in a variable of an appropriate type. In the 
above example, the variable range must be of type NSRange. Messages that 
return values can be nested , especially if those returned values are objects. By 
enclosing one message expression within another, you can use a returned value 
as an argument or as a receiver without having to declare a variable for it. 

newString = [stringOne stringByAppendingString: 

[substringFromRange: 

[stringTwo rangeOfString:@"OPENSTEP" at:NSAnchoredSearch]]]; 

The above message nests two other messages, each of which returns a value 
used as an argument. The inmost message expressions is resolved first, then the 
next nested message expression is resolved, then the third message is sent and 
a value is returned to newString. 
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An Objeri-Oriented Program 

Object-oriented programming is more than just another way of organizing data 
and functions. It permits application programmers to conceive and construct 
solutions to complex programs using a model that resembles—much more so 
than traditional programs—the way we organize the world around us. The 
object-oriented model for program structure simplifies problem resolution by 
clarifying roles and relationships. 

You can think of an object-oriented program as a network of objects with well- 
defined behavior and characteristics, objects that interact through messages. 



Different objects in the network play different roles. Some correspond to 
graphical elements in the user interface. The elements that you can drag from 
an Interface Builder palette are all objects. In an application, each window is 
represented by a separate object, as is each button, menu item, or display of text. 

Applications also assign to objects functionality that isn’t directly apparent in the 
interface, giving each object a different area of responsibility. Some of these 
objects might perform very specific computational tasks while others might 
manage the display and transfer of data, mediating the interaction between 
user-interface objects and computational objects. 

Once you’ve defined your objects, creating a program is largely a matter of 
“hooking up” these objects: creating the connections that objects will use to 
communicate with each other. 
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Polymorphism and Dynami< Binding 

Although the purpose of a message is to invoke a method, a message isn’t the 
same as a function call. An object “knows about” only those methods that were 
defined for it or that it inherits. It can’t confuse its methods with another object’s 
methods, even if the methods are identically named. 

Each object is a self-contained unit, with its own name space (an name space 
being an area of the program where it is uniquely recognized by name). Just as 
local variables within a C function are isolated from other parts of a program, so 
too are the variables and methods of an object. Thus if two different kinds of 
objects have the same names for their methods, both objects could receive the 
same message, but each would respond to it differently. The ability of one 
message to cause different behavior in different receivers is referred to as 
polymorphism . 

Polymorphism 



The example of display highlights 
the role of inheritance in 
polymorphism: a subclass often 
implements an identically named 
method (that is, overrides the 
method) of its superclass to achieve 
more specialized behavior. See the 
following section, “Classes,” for 
details. 


The advantage polymorphism brings to application developers is significant. It 
helps improve program flexibility while maintaining code simplicity. You can 
write code that might have an effect on a variety of objects without having to 
know at the time you write the code what objects they might be. For example, 
most user-interface objects respond to the message display; you can send display 
to any of these objects in your interface and it will draw itself, in its own way. 

Dynamic bindings perhaps even more useful than polymorphism. It means both 
the object receiving a message and the message that an object receives can be 
set within your program as it runs. This is particularly important in a graphical, 
user-driven environment, where one user command—say Copy or Paste—may 
apply to any number of user-interface objects. 
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Dynamic Binding 



In dynamic binding, a run-time process finds the method implementation 
appropriate for the receiver of the message; it then invokes (or calls, in a sense) 
this implementation and passes it the receiver’s data structure. This mechanism 
makes it easier to structure programs that respond to selections and actions 
chosen by users at run time. For example, either or both parts of a message 
expression—the receiver and the method name—can be variables whose values 
are determined by user actions. A simple message expression can deliver a Cut, 
Copy, or Paste menu command to whatever object controls the current 
selection. 

Dynamic binding even enables applications to deal with new kinds of objects, 
ones that were not envisioned when the application itself was built. For 
example, it lets Interface Builder send messages to objects such as EOModeler 
when it is loaded into the application by means of custom palettes. 

Polymorphism and dynamic binding depend on two other features: dynamic 
typingznd introspection . The Objective-C language allows you to identify objects 
genetically with the data type of id. This type defines a pointer to an object and 
its data structure (that is, instance variables) which, by inheritance from the root 
class NSObject, include a pointer to the object’s class. What this means is that 
you don’t have to type objects strictly by class in your code: the class for the 
object can be determined at run time through introspection. 

Introspection means that an object, even one typed as id, can reveal its class and 
divulge other characteristics at run time. Several introspection methods allow 
you to ascertain the inheritance relationships of an object, the methods it 
responds to, and the protocols that it conforms to. 
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Classes 


Some of the objects networked together in an applications are of different kinds, 
and some might be of the same kind. Objects of the same kind belong to the 
same class. A class is a programmatic entity that creates instances of itself— 
objects. A class defines the structure and interface of its instances and specifies 
their behavior. 

When you want a new kind of object, you define a new class. You can think of a 
class definition as a type definition for a kind of object. It specifies the data 
structure that all objects belonging to the class will have and the methods they 
will use to respond to messages. Any number of objects can be created from a 
single class definition. In this sense, a class is like a factory for a particular kind 
of object. 

In terms of lines of code, an object-oriented program consists mainly of class 
definitions. The objects the program will use to do its work are created at run 
time from class definitions (or, if pre-built with Interface Builder, are loaded at 
run time from the files where they are stored). 

A class is more than just an object “factory,” however. It can be assigned 
methods and receive messages just as an object can. As such it acts as a class 
object. 


Objetf Creation 

One of the primary functions of a class is to create new objects of the type the 
class defines. For example, the NSButton class creates new NSButton objects 
and the NSArray class creates new NSArrays. Objects are created at run time in 
a two-step process that first allocates memory for the instance variables of the 
new object and then initializes those variables. The following code creates a 
new Country object: 


You can create objects in your code 
with the alloc and init methods 
described here. But when you 
define a class in Interface Builder, 
that class definition is stored in a 
nib file. When an application loads 
that nib file, Interface Builder 
causes an instance of that class to 
be created. 


id newCountry = [[Country alloc] init]; 

The receiver for the alloc message is the Country class (from the Travel Advistor 
application in the next tutorial). The alloc method dynamically allocates 
memory for a new instance of the receiving class and returns the new object. 
The receiver for the init message is the new Country object that was 
dynamically allocated by alloc. Once allocated and initialized, this new record is 
assigned to the variable newCountry. 

After being allocated and initialized, a new object is a fully functional member 
of its class with its own set of variables. The newCountry object has all the 
behavior of any Country object, so it can receive messages, store values in its 
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instance variables, and do all the other things a Country object does. If you need 
other Country objects, you create them in the same way from the same class 
definition. 

Objects can be typed as id, as in the above example, or can be more restrictively 
typed, based on their class. Here, newCountry is typed as a Country object: 

Country *newCountry = [[Country alloc] init]; 

The more restrictive typing by class enables the compiler to perform type¬ 
checking in assignment statements. 

Inheritance 

Inheritance is one of the most powerful aspects of object-oriented programming. 
Just as people inherit traits from their forbearers, instances of a class inherit 
attributes and behavior from that class’s “ancestors.” An object’s total 
complement of instance variables and methods derives not only from the class 
that creates it, but from all the classes that class inherits from. 

Because of inheritance, an Objective-C class definition doesn’t have to specify 
every method and variable. If there’s a class that does almost everything you 
want, but you need some additional features, you can define a new class that 
inherits from the existing class. The new class is called a subclass of the original 
class; the class it inherits from is its superclass . 


Instance of superclass 

Instance of subclass 


Creating a new class is often a matter of specialization. Since the new class 
inherits all its superclass’s behavior, you don’t need to reimplement the things 
that work as you want them to. The subclass merely extends the inherited 
behavior by adding new methods and any variables needed to support the 
additional methods. All the methods and variables defined for—or inherited 
by—the superclass are inherited by the subclass. A subclass can also alter 
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Other root classes are possible. In 
fact, OPENSTEP’s Distributed 
Objects makes use of another root 
class, NSProxy. 


superclass behavior by overriding ^ inherited method, reimplementing the 
method to achieve a behavior different from the superclass’s implementation. 
(The technique for doing this is discussed later.) 

The Class Hierarchy and the Root Class 

A class can have any number of subclasses, but only one superclass. This means 
that classes are arranged in a branching hierarchy, with one class at the top—the 
root class —that has no superclass: 


C 


NSObject 


Part of the OpenStep class 
hierarchy. 
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NSResponder 
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NSString 


NSWindow 


NSView 


NSApplication 
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NSControl 
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NSForm 
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NSObject is the root class of this hierarchy, as it is of most Objective-C class 
hierarchies. From NSObject, other classes inherit the basic functionality that 
makes messaging work, enables objects to work together, and otherwise invests 
objects with the ability to behave as objects. Among other things, the root class 
creates a framework for the creation, initialization, deallocation, introspection, 
and storage of objects. 

As noted earlier, you often create a subclass of another class because that 
superclass provides most, but not all, the behavior you require. But a subclass 
can have its own unique purpose that does not build on the role of an existing 
class. To define a new class that doesn’t need to inherit any special behavior 
other than the default behavior of objects, you make it a subclass of the 
NSObject class. Subclasses of NSObject, because of their general-purpose 
nature as objects, are very common in OpenStep applications. They often 
perform computational or application-specific functions. 
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Advantages of Inheritance 

Inheritance makes it easy to bundle functionality common to a group of classes 
into a single class definition. For example, every object that draws on the 
screen—whether it draws an image of a button, a slider, a text display, or a graph 
of points—must keep track of which window it draws in and where in the 
window it draws. It must also know when it’s appropriate to draw and when to 
respond to a user action. The code that handles all these details is part of a single 
class definition (the NSView class in the Application Kit). The specific work of 
drawing a button, a slider, or a text display can then be entrusted to a subclass. 

This bundling of functionality both simplifies the organization of the code that 
needs to be written for an application and makes it easier to define objects that 
do complicated things. Each subclass need only implement the things it does 
differently from its superclass; there’s no need to reimplement anything that’s 
already been done. 

What’s more, hierarchical design assures more robust code. By building on a 
widely used, well-tested class such as NSView, a subclass inherits a proven 
foundation of functionality. Because the new code for a subclass is limited to 
implementing unique behavior, it’s easier to test and debug that code. 

Any class can be the superclass for a new subclass. Thus inheritance makes 
every class easily extensible—those provided by OpenStep, those you create, 
and those offered by third party vendors. 

Defining a Class 

You define classes in two parts: One part declares the instance variables and the 
interface, principally the methods that can be invoked by messages sent to 
objects belonging to the class, and the other part actually implements those 
methods. The interface is public. The implementation is private, and can 
change without affecting the interface or the way the class is used. 

The basic procedure for defining a class (using Interface Builder) is covered in 
the Currency Converter tutorial. However, here is a supplemental list of 
conventions and other points to remember when you define a class: 

• The public interface for a class is usually declared in a header file (.h 
extension), the name of which is the name of the class. This header file can 
be imported into any program that makes use of the class. 

• The code implementing a class is usually in a file taking the name of the class 
and having an extension of .m. This code must be present—in the form of a 
framework, dynamic shared library, static library, or the implementation file 
itself—when the project containing the class is compiled. 
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• Method declarations and implementations must begin with and - sign or a + 
sign. The dash indicates that these methods are used by instances of the class; 
a + sign precedes methods that the class object itself uses. 

• Method definitions are much like function definitions. Note that methods not 
only respond to messages, they often initiate messages of their own—just as 
one function might call another. 

• In a method implementation you can refer directly to an object’s instance 
variables, as long as that object belongs to the class the method is defined in. 
There’s no extra syntax for accessing variables or passing the object’s data 
structure. The language keeps all that hidden. 

• A method can also refer to the receiving object as self. This variable makes it 
possible for an object, in its method definitions, to send messages to itself. 

Overriding a Method 

A subclass can not only add new methods to the ones it inherits, it can also 
replace an inherited method with a new implementation. No special syntax is 
required; all you do is reimplement the method. 

Overriding methods doesn’t alter the set of messages that an object can receive; 
it alters the method implementations that will be used to respond to those 
messages. As mentioned earlier, this ability of each class to implement its own 
version of a method is referred to as polymorphism. 

It’s also possible to extend an inherited method, rather than replace it outright. 
To do this you override the method but invoke the superclass’s same method in 
the new implementation. This invocation occurs with a message to super, which 
is a special receiver in the Objective-C language. The term super indicates that 
an inherited method should be performed, rather than one defined in the 
current class. 
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Categories and Protocols 

In addition to subclassing, you can expand an object and make it fit with other 
classes using two Objective-C mechanisms: categories and protocols. 

Categories provide a way to extend classes defined by other implementors—for 
example, you can add methods to the classes defined in the OPENSTEP 
frameworks. The added methods are inherited by subclasses and are 
indistinguishable at run-time from the original methods of the class. Categories 
can also be used as a way to distribute the implementation of a class into groups 
of related methods and to simplify the management of large classes where more 
than one developer is responsible for components of the code. 

Protocols provide a way to declare groups of methods independent of a specific 
class—methods which any class, and perhaps many classes, might implement. 
Protocols declare interfaces to objects, leaving the programmer free to choose 
the implementation most appropriate to a specific class. Protocols free method 
declarations from dependency on the class hierarchy, so they can be used in 
ways that subclasses and categories cannot. They allow objects of any class to 
communicate with each other for a specific purpose. 

OpenStep provides a number of protocols. For example, the spell-checking 
protocols and the object-dragging protocols enable other developers to 
seamlessly integrate their spell-checking and object-dragging implementations 
into an existing system. 
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userlnfo dictionary 153 


V 

validation, of fields 96,169 
value object 68, 83 
view hierarchy 18,140, 141 
view object 18, 32,120 
custom 112,172 
printing 65 

removing from superview 169 
Views palette 20,172 

W 

WebObjects 5,136,187 
window 18, 154 
attributes 19 
behavior 28 
closing 143 
depth 171 
events 155 
key 18 
locating 136 
main 18 

making first responder 143 
positioning 135 
resizing 19 
setting title 136 
status 138 

Window Server 18, 108,140,154 
Windows, menu 24 
Windows operating system 4 
Windows palette 157 
windowShouldClose: 143 
World Wide Web 187,195 

Y 

Yap application 188 


232 





